Using Incredibuild on Docker Containerized Agents

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. The Docker Desktop cannot 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).

Download and Prepare the Incredibuild Image on Docker

The Incredibuild images contain the windows server core 2022 operating system, the Incredibuild installer, and the Incredibuild initialization script. They include an Incredibuild Agent with a license and different roles depending on the image you use.

  1. Download an Incredibuild Image

    To download one of the Incredibuild images, use the following command:

    docker pull incredibuild/<role>:<version>

    Where:

    • <role> is the role or roles that will be assigned to the Incredibuild Agent [helper, initiator, both].

    • <version> must be 10.2.1.

    For example:

    docker pull incredibuild/initiator:10.2.1

  2. Modify the Incredibuild Image (for Initiator Agents)

    If you want to use a Container as an Initiator you need to create a modified Dockerfile based on the Incredibuild Initiator image, and add any build tools and files required to run the build to that container.

    FROM incredibuild/10.2.1/initiator

    RUN mkdir C:\\BuildTools

    WORKDIR C:\\BuildTools

    COPY C:\\Host\\BuildToolsDirectory . # (change this to the path of any tools required to run your build) 

    Build the image using the docker build command.

  3. Creating a custom Incredibuild Image (optional)

    The Incredibuild installer is included in the Incredibuild image. However, if you already have a Dockerfile and want to manually add the Incredibuild installer to your image, use the following procedure.

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

    2. Edit your Dockerfile as seen in the following example:

    Copy 
    FROM mcr.microsoft.com/windows/servercore:ltsc2016

      RUN mkdir C:\\Installers

      COPY C:\\Path\\To\IncrediBuild\Version_9_5_0_ConsoleInstaller.exe C:\\Installers\\IB_ConsoleInstaller.exe

      RUN C:\\Installers\\IB_ConsoleInstaller.exe /               # Run IncrediBuild console installer.
                && /install /                                     # Install. Other options are /repair, /update, /uninstall.
                && /installdir="C:\IncrediBuild\InstallDir" /     # Set installation directory.
                && /components=agent /                            # Install Agent component only. In case of using the 'suvm' tag, use "/components=agent,oneuse".
                && /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.

      RUN mkdir C:\\BuildTools

      WORKDIR C:\\BuildTools

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

    Note: 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.

  4. 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