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_MAINTAINER="fullgx <>" 

Deploy to docker of a command line procedure

If your deployment unit has only one object, and this object is a main procedure with Call protocol property = "Command line", the Dockerfile generated adds an EntryPoint to be able to execute this procedure when the image is run.

You have to set the DOCKER_BASE_IMAGE property with an adequate value for that purpose; for example, OpenJDK:15.

In the case of deploying command line procedures, the GXDeployFileProject property is mandatory. In case of not passing it in Java, the msbuild execution throws an error.
For .NET it throws the following warning:
warning : Missing or invalid GXDeployFileProject property. It should be set for command line deployments.

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 the configuration file (.json) that should be 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, which must be in the root of GeneXus.

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

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

"Taking default values ​​for Base Image and Image WebApp Location from 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 is read and the user is warned:

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

(1)The file looks as follows:

    "Images": {
        ".NET Framework": "genexus/dotnet:4.6.2",
        ".NET": "",
        "C#": "genexus/dotnet:4.6.2",
        ".NET Core": "",
        "Java": "tomcat:10-jdk15-openjdk-oracle"
    "CMDAppImages": {
        ".NET Framework": "genexus/dotnet:4.6.2",
        ".NET": "",
        "C#": "genexus/dotnet:4.6.2",
        ".NET Core": "",
        "Java": "openjdk:15"
    "WebAppLocation": {
        ".NET Framework": "c:/inetpub/wwwroot/",
        ".NET": "/app",
        "C#": "c:/inetpub/wwwroot/",
        ".NET Core": "/app",
        "Java": "/usr/local/tomcat/webapps/"
    "AppLocation": {
        ".NET Framework": "/app",
        ".NET": "/app",
        "C#": "/app",
        ".NET Core": "/app",
        "Java": "/usr/src/myapp"

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


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 <>" /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. In particular (in addition to some other differences), 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). This corresponds to the DOCKER_CONTAINER_RUNTIME MSBuild property.

When the container is Openshift, the "Registry Image" property becomes visible. Through it, 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:DOCKER_MAINTAINER="fullgxops <>"
/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 to the machine once; 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 generator, 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