Integrating with Docker - IncrediBuild Documentation

Last updated on Nov 05, 2024 You can use Docker containers to launch and run Incredibuild Helper and Initiator Agents. Docker technology allows you to create multiple containers on a single host, and therefore allows you to use one powerful machine to provide multiple users with Helper agents. Installing agents on containers also provides you a greater flexibility in starting, stopping, removing, and re-launching Agents. With a few commands, you can set up and manage your containerized Agents across your entire Incredibuild Environment.

Requirements

A Docker Desktop on each machine that will host containers with Incredibuild. We recommend that the Docker Desktop not be on a virtual machine.
An Incredibuild Coordinator with floating licenses (helper and/or initiator) that will be automatically assigned and unassigned to the Agents you create.
Verify that you can run builds without Incredibuild in your Docker environment before launching containers with Incredibuild images.
The Docker Desktops must be set to Windows Containers (by default it is set to run Linux containers).
Containerised Agents cannot run on Microsoft Nano Server OS, since this OS can run only 64-bit based applications, and a part of IncrediBuild’s applications are 32-bit based.

Prepare the Incredibuild Image

To install an Incredibuild Agent used to run builds on a Docker Container, edit your Dockerfile to include the Incredibuild installation script.

Obtain an Incredibuild installer file. For details, see Silent Installation.

Edit your Dockerfile as seen in the following example: Copy

FROM mcr.microsoft.com/windows/server:ltsc2022

RUN mkdir C:\\Installers

#assumes your Incredibuild installer file is called ibsetup.exe
COPY ibsetup.exe . C:\\Installers\\ 

RUN C:\\Installers\\ibsetup.exe /                             # Run IncrediBuild console installer.
            && /install /                                     
            && /installdir="C:\IncrediBuild\InstallDir" /     # Set installation directory.
            && /components=agent /                            # Install Agent component only. 
            && /coordinator=192.168.10.10:31104 /             # Connect to the Coordinator in IP address 192.168.10.10, that is listening on port 31104.
            && /agent:serviceport=31105 /                     # Set BuildService port.
            && /agent:helperport=31106                        # Set BuildHelper(s) port(s), according to the allocated CPUs for the container, which is automatically detected by the installer.
            && /agent:agentrole=Initiator                     # Install Agent component only. 
            && /agent:initiatorType=floating                  # Ask for floating initiator license when connecting to the grid 

RUN mkdir C:\\BuildTools

WORKDIR C:\\BuildTools

COPY C:\Path\To\Host\BuildToolsDirectory . # (import build tools and necessary binaries)

The example above installs an Agent with the Initiator role. To install an Agent with a Helper role, modify the agentrole parameter as follows: && /agent:agentrole=helper.
You can now launch containers using the Incredibuild images as described below.

Launch a Container using the Incredibuild Image

To launch a container, use the following command: Copy

docker run --cpus <Max_No._of_Cores_to_Use> 
-e Coordinator=<Coordinator_Machine_IP_Adddress_or_Hostname> 
-e CoordinatorPort=<Coordinator_Port_No.> 
-e BuildServicePort=<Agent_Port_No._for_Coordinator_Communication>
-e BuildHelperPort=<First_Agent_Port_No._in_a_Range_for Communicating_with_the_Agent_Cores>" 
-it 
-p <Host_Machine_Port_No._mapped to>:<BuildServicePort No._in the_Container>/tcp 
-p <Start-End_Port_Range_in the Host_Machine_mapped_to>:
<Start-End_Port_Range_for_the_Agent_Cores_in_the Container>/tcp 
<IncrediBuild_Image>

Where:

Flag	Required/Optional	Description
`--cpus`	Optional	The maximum number of CPU cores to be used by the containerized Agent. If nothing is specified, the default is 2.
e Coordinator=	Required	The IP address or hostname of the Incredibuild Coordinator that the Agent is associated with.
-e CoordinatorPort=	Optional	The Coordinator port required for communication with the Agent. 31104 by default.
-e BuildServicePort=	Optional	The Service port required for the communication with the Coordinator. 31105 by default.
-e BuildHelperPort=	Optional	The first Helper port. Every core requires a unique helper port, and they are assigned consecutively from the number you specify. So if you use the default 31106 and you have 4 cores, the ports 31106-31109 will be used as the Helper ports.
-it	Required	A general docker run option required for use with Incredibuild.
-p <Host_Machine_Port_No._mapped to>:<BuildServicePort No.>/tcp	Required	The mapping of the Build Service port from the Container to the Build Service port on the host machine. In general, even if you have multiple containers on one host, these numbers can all be the same. By default, it is 31105 and would look like this: -p 31105:31105/tcp.
-p <Start-End_Port_Range_in the Host_Machine_mapped_to>:<Start-End_Port_Range_for_the_Agent_Cores_in_the Container>/tcp	Required	The mapping of the Build Helper ports from the Container to the Build Helper ports on the host machine. Each Helper core requires a unique port on the host machine. By default, these start at 31106 and continue consecutively. If you have more than one Container on the host machine, map carefully. For example, if you have two Containers allocated with 4 cores each on the same host, your mapping for the first container might be -p 31106-31109:31106-31109/tcp and the mapping of the second container might be -p 31106-31109:31110-31113/tcp.
<Incredibuild_Image>	Required	The name of Incredibuild image that was downloaded to the machine. For example, Incredibuild:9.5.0.

The containerized Agent names are based on the container ID and hostname. If you want to give a meaningful name to a containerized Agent, use the --hostname Docker option to specify an internal hostname for your container, which will be manifested in the containerized Agent name.

Advanced Options

Adding Standard Docker Options to Incredibuild Docker Run Command

You can use standard options of the docker run command, as part of the Incredibuild container creation docker run command. For a detailed list of available docker run options, see: https://docs.docker.com/engine/reference/run/ In Incredibuild container creation command, add the standard Docker option BETWEEN the docker run command and the specified Incredibuild image. For example, if you want to automatically clean up the container and remove its file system when it exits, use the --rm command as follows: Copy

docker run --cpus 4 
-e Coordinator= Incredibuild1 
-e CoordinatorPort=31104 
-e BuildServicePort=31105 
-e BuildHelperPort=31106 
--rm 
-it 
-p 31105:31105/tcp 
-p 31106-31109:31106-31109/tcp Incredibuild:9.5.0

Initializing Additional Processes during Container Launch

You can initialize additional process when an Incredibuild container is launched such as building a solution, running a script, or starting a server. You can only add one additional process to Incredibuild docker run command. If you want to initialize multiple processes upon the Incredibuild container launch, use a script to bundle these processes. In Incredibuild docker run command, add the initialization command and arguments of the additional process AFTER the specified Incredibuild image. For example: Copy

docker run --cpus 4 
-e Coordinator= IncrediBuild1 
-e CoordinatorPort=31104 
-e BuildServicePort=31105 
-e BuildHelperPort=31106 
-it 
-p 31105:31105/tcp 
-p 31106-31109:31106-31109/tcp 
incredibuild:9.4.6 
MSBuild.exe MySolution.sln /t:rebuild /v:q

Unassigning Licenses from Docker Agents

If you stop, remove, or terminate an Incredibuild container, the license that was assigned to the containerized Agent is not automatically unassigned unless it is a floating license. If you want to unassign a license that was assigned to an Agent in a Docker container, you need to manually Unassign it. For more details, see Managing Licenses

​Requirements

​Prepare the Incredibuild Image

​Launch a Container using the Incredibuild Image

​Advanced Options

​Adding Standard Docker Options to Incredibuild Docker Run Command

​Initializing Additional Processes during Container Launch

​Unassigning Licenses from Docker Agents