Deploy to Docker MSBuild task

Official Content
This documentation is valid for:

To deploy to Docker, there is an MSBuild script to build the Docker image.

Docker is an external target, and for all external targets there is a deploy.msbuild file (located in the GeneXus installation, under the DeploymentTargets folder). In the case of Docker deployment target, the deploy.msbuild file is under <GeneXus installation>\DeploymentTargets\Docker, and it defines a default task called Deploy. For more information about this topic, see Docker deployment target.

Sample to call the MSBuild to build a Docker image

After having run the two previous MSBuild scripts, as described in Application Deployment MSBuild tasks, you can execute the following command to have a Docker image built.

MSBuild.exe /nologo /verbosity:minimal /ToolsVersion:4.0 "c:\GeneXus\DeploymentTargets\Docker\deploy.msbuild" 
/p:DOCKER_BASE_IMAGE="tomcat:9-jdk14-openjdk-oracle" 
/p:DOCKER_MAINTAINER="fullgx <fullgx@example.com>" 
/p:DOCKER_WEBAPPLOCATION="/usr/local/tomcat/webapps/" 
/p:DOCKER_IMAGE_NAME="k8sdeployjavaenvironment" 
/p:DOCKER_ENVVARS=""
/p:GENERATOR="Java" 
/p:APPLICATION_NAME="DeploymentUnit2_20200130131103" 
/p:DEPLOY_PATH="C:\GXmodels\junk\K8SDeploy\JavaModel\Deploy\DOCKER\DeploymentUnit2\20200130131103" 
/t:Deploy

Taking some properties from a configuration file

The DOCKER_BASE_IMAGE and DOCKER_WEBAPPLOCATION properties can be taken from a configuration file and you can avoid adding their definitions to the MSBuild execution.

The mechanism is as follows:

1. If the DOCKER_BASE_IMAGE and DOCKER_WEBAPPLOCATION properties are specified when the MSBuild is run; they are taken from there. 

2. If both or either of them are empty the "BuildEnvironment" property is verified, which indicates which configuration file (.json) to read to extract the information from these properties.

The BuildEnvironment property indicates the environment to which this build corresponds.

For example, if you have / p: BuildEnvironment = dev, it looks for docker.dev.json, which must be in the root of GeneXus.

The file format must be the same as the docker.prod.json that is distributed with GeneXus (1)

If the file cannot be found, an error occurs similar to the following:

"Taking default values ​​for Base Image and Image WebApp Location from docker.dev.json file.
Configuration file not found and default parameters not set. Base Image and Image WebApp Location cannot be empty."

3. If at least one of the properties (DOCKER_BASE_IMAGE and DOCKER_WEBAPPLOCATION) in the MSBuild command is not referenced and the BuildEnvironment property is not indicated, by default docker.prod.json is read and the user is warned:

"Taking default values ​​for Base Image and Image WebApp Location from docker.prod.json file."

(1)The docker.prod.json file looks as follows:

{
    "Images": {
        "C#": "genexus/dotnet:4.6.2",
        ".NET Core": "mcr.microsoft.com/dotnet/core/aspnet:3.1",
        "Java": "tomcat:9-jdk14-openjdk-oracle"
    },
    "WebAppLocation": {
        "C#": "c:/inetpub/wwwroot/",
        ".NET Core": "/app",
        "Java": "/usr/local/tomcat/webapps/"
    }
}

Note: The .json file is read considering the "Generator" MSBuild property. This property must be set using the same casing as in the configuration file.

Otherwise, the MSBuild execution throws the error: "The given key was not present in the dictionary."

Example: 

MSbuild.exe /nologo /verbosity:normal /ToolsVersion:14.0 "c:\genexus\DeploymentTargets\Docker\deploy.msbuild" /p:DeploySource="c:\kbaux\Deploy\JavaModel\Docker\kbauxJavaEnvironmentDeploy.war" /p:DOCKER_MAINTAINER="fullgxops <fullgxops@genexus.com>" /p:DOCKER_IMAGE_NAME="kbauxjavaenvironment" /p:GENERATOR="Java" /p:BuildEnvironment=dev /t:Deploy /l:FileLogger,Microsoft.Build.Engine;logfile=c:\fullgx\temp\DeployDocker.log 

Availability: The configuration file is read since GeneXus 17 upgrade 3

Deploying the image to Openshift

OpenShift is an orchestrator standing on Kubernetes. It has some additional security restrictions. What is mainly particular (in addition to some other differences), is that this platform runs any container using a ramdon UUID. So if the docker image is not ready to run as non-root, errors will occur.

In order to deploy to Openshift, the "Container" property = {Default, Openshift} is available in the Deploy Target Docker Image properties (only for Java and Net core). This corresponds to the DOCKER_CONTAINER_RUNTIME msbuild property.

When the container is Openshift, the "Registry Image" property becomes visible through which the registry of the base image {Docker hub, Redhat registry} can be selected. The corresponding msbuild property is DOCKER_IMAGE_REGISTRY.

The msbuild in this case is as follows:

MSbuild.exe /nologo /verbosity:normal /ToolsVersion:14.0 "c:\fullgx\gxsalto\DeploymentTargets\Docker\deploy.msbuild"
/p:DeploySource="c:\fullgx\kbaux\Deploy\NetCoreModel\Docker\DeployNet.zip"
/p:DOCKER_BASE_IMAGE=mcr.microsoft.com/dotnet/core/aspnet:3.1
/p:DOCKER_MAINTAINER="fullgxops <fullgxops@genexus.com>"
/p:DOCKER_WEBAPPLOCATION="/app"
/p:DOCKER_IMAGE_NAME="kbauxnetcoreenvironment"
/p:GENERATOR=".NET Core"
/p:DOCKER_CONTAINER_RUNTIME=Openshift
/p:DOCKER_IMAGE_REGISTRY=DockerHub
/t:Deploy /l:FileLogger,Microsoft.Build.Engine;logfile=c:\fullgx\temp\DeployDocker.log 

Note that :

1. If Redhat registry is chosen, in "Base Image" property (DOCKER_BASE_IMAGE msbuild property) an image from the Redhat image catalog must be entered.

To authenticate and download the base image, using the docker command, it is enough to log in once on the machine, then the credentials will be saved in a credentials store ($HOME/.docker/config.json on Linux or %USERPROFILE%/.Docker/config.json on Windows) See this reference. For more information about authentication when downloading images from Redhat see here.

2. When images are non-root, they cannot listen on ports less than 1024.
In the case of Net core, when running the image, the user must use the -expose option to indicate a port that is allowed taking into account this restriction.

Availability: This is available since GeneXus 17 upgrade 3.

See also