Launching a Container Based on Incredibuild Docker Image

Once Incredibuild image is stored on your host machine, you need to use the docker run command in order to run the image and launch a container that is based on it.

> To run Incredibuild image as a container:

  • In PowerShell or the terminal, enter the following command to launch a container based on Incredibuild image:

    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:

  • --cpus [Optional] – the maximum number of CPU cores to be used by the containerized Agent. The default maximum number of cores is 2. If no number is specified, the default number will take effect.For example, if you want the Agent to use 8 cores or less, enter: --cpus 8.When setting this CPU number, take into consideration the number of CPU cores that the host machine has, how many of these available cores you want to allocate to the container, and whether additional Incredibuild containers will run on this host machine.

  • -e Coordinator= [Mandatory] – the IP address or hostname of the Coordinator that will communicate with the containerized Agent.For example, to connect the Agent to a Coordinator whose IP address is 172.0.0.0, enter: -e Coordinator=172.0.0.0.  

  • -e CoordinatorPort= [Optional] – the Coordinator port number for the communication with the Agent. By default, the Coordinator port no. is 31104. If no other port no. is specified, the default will take effect.For example, to use port 20001 on the Coordinator machine for the communication with the Agent, enter: -e CoordinatorPort=20001.

  • -e BuildServicePort= [Optional] – the Agent port number for the communication with the Coordinator. By default, the BuildService port no. of an Agent is 31105. If no other port no. is specified, the default will take effect.For example, to allocate port 40001 on the container for the communication between the Agent and the Coordinator, enter: -e BuildServicePort=40001.

  • -e BuildHelperPort= [Optional] – the first Agent port number in a port range, for the communication between an Initiator and the containerized Agent cores. For each available core in the containerized Agent, a port no. in a consecutive order should be open and available. For example, if the first port no. in the range is 32000, and the Agent has 4 cores, 3 additional ports should be open: 32001, 32002, 32003.By default, the BuildHelper port of an Agent is 31106. If no other port no. is specified, the default will take effect. The number of available Agent cores that will be included in the range depends on the value of the --cpus parameter.For example, to allocate ports 32000-32003 on the container for the communication with the 4 cores of the containerized Agent, enter: -e BuildHelperPort=32000.

  • -it [Mandatory] – a general docker run option enabling you to log into a container using TTY, i.e. a terminal, and preventing the container from exiting immediately after the launch.

  • -p <Host_Machine_Port_No._mapped to>:<BuildServicePort No.>/tcp [Mandatory] – the mapping of a physical open port in the host machine to the port no. of the BuildServicePort in the container. For the communication with the Coordinator, the Agent in the container needs an open port. This port should be mapped to an open port in the host machine, to enable the communication with the Coordinator machine. These port numbers on the host machine and container do not have to be the same.For example, for the communication with the Coordinator, to map port 30044 on the host machine to port 40001 on the container, enter: -p 30044:40001/tcp.Note: If you did not specify a port no. for the BuildService, and you used the default port number, you need to enter here the default no. 31105. For example, -p 30044: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 – the mapping of a physical port range in the host machine to the port range of the BuildServicePort in the container. For the communication between an Initiator and the containerized Agent cores, a range of ports needs to be open in the container, and this port range should be mapped to port range in the host machine to enable the communication. These port ranges on the host machine and container MUST be the same.For example, for the communication with the 4 cores of a containerized Agent, to map port range 32000-32003 on the host machine to port range 32000-32003 on the container, enter: -p 32000-32003:32000-32003/tcp.Note: If you did not specify a port no. for the BuildHelper, and you used the default port number, you need to enter here the default number 31106 as the first port no. in the range of the container. For example, -p 31106-31109:31106-31109/tcp.

  • <Incredibuild_Image> [Mandatory] - the name of Incredibuild image that was downloaded to the machine. For example, Incredibuild:9.5.0.

For example, the following command was entered in a terminal, to launch an Incredibuild container with an active Agent:

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

In this example:

  • --cpus – the maximum number of cores that can be used by the containerized Agent is 4.

  • -e Coordinator= – the Agent will communicate with a Coordinator whose hostname is Incredibuild1.

  • -e CoordinatorPort= – the Coordinator port number for the communication with the Agent is 31104.

  • -e BuildServicePort= – the Agent port number for the communication with the Coordinator is 31105.

  • -e BuildHelperPort= – the first Agent port number in the port range for the communication with the Agent cores is 31106. Since the Agent can use up to 4 cores, 3 additional ports in a consecutive order should to be open in the container: 31107, 31108, 31109.

  • -it - general docker run option for logging into the container using TTY.

  • -p 31105:31105/tcp – port number 31105 on the host machine is mapped to port number 31105 on the container, for the communication between the containerized Agent and the Coordinator.

  • -p 31106-31109:31106-31109/tcp – port range 31106-31109 on the host machine is mapped to port range 31106-31109 on the container, for the for the communication between the containerized Agent cores and an Initiator.

  • <Incredibuild_Image> – Incredibuild image that is used for launching the container is Incredibuild/9.5.0.

 Output:

Copy 
Setting Coordinator to IncrediBuild1
Setting Coordinator Port to 31104
Setting BuildService Port to 31105
Setting BuildHelper Port to 31106
Starting IncrediBuild Agent Service

Once the container is launched, a new active containerized Agent is being added to Incredibuild Environment. This new Agent is subscribed to the Coordinator whose details were entered in the docker run command, and it is displayed in the Coordinator Monitor:

Notes:

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

  • If you want to use a containerized Agent as an Initiator, you should take into consideration that the container is isolated from its host, and therefore it cannot rely on the host filesystem and installed environment. If, for example, you want to build a Visual Studio project from a containerized Agent, you need to install Visual Studio on the container, and to copy your projects to the container in order to run them from it.

  • If you stop, remove, or terminate an Incredibuild container, you should be aware that the license that was assigned to the containerized Agent is not automatically released to your license pool. If you want to deallocate the license that was assigned to a containerized Agent, in order to re-assign it later to a different Agent, you need to Unsubscribe it like with any other Agent, as described below.

> To deallocate a license from a containerized Agent:

  • On the Coordinator Monitor, select the containerized Agent, and right-click it. From the pop-up menu, select the Unsubscribe option:Note: You can also open the Agent menu in the Coordinator Monitor, and select the Unsubscribe option.

    The license that was allocated to the Agent will return to your license pool, and the containerized Agent will be removed from the Coordinator Monitor.