Use the steps described in this article to easily deploy and run Java, .NET Framework and .NET generated applications in a Docker Container.
Note that these steps help you to deploy the generated programs, not the database. To deploy the database, see Export Reorganization. For further options, see Application Deployment tool.
1. Before you deploy your application for the first time to a specific target (e.g., production), creating a new environment in the Knowledge Base is recommended, so that it:
- Runs locally in the Tomcat or IIS of the computer used to work with GeneXus, and
- Is connected to the target (e.g., production) database.
2. Select Build All.
3. Go to the Build menu and select the Application Deployment tool option.
4. In the Deployment screen:
1. Select the Main objects to be included in the deployment.
2. In Target, select the option "Docker Image".
3. Set the following properties as indicated below (All fields have default values):
1. Docker base image property: Image that is used as a base to create the new one
2. Maintainer name property: Name of the Author of the image; it's set as part of the metadata of the image
3. Docker Environment variables property: All the environment variables you wish the image to have already instanced
4. Image WebApp location property: Path inside the docker image where the application runs
5. Docker image name property: Name of the generated docker image
5. Click on the Deploy button to create the Docker Image. The Output sends feedback about the process and the location of the generated files.
Now run the following command, in the Windows command prompt, to list the Docker images, including the one you created in the previous steps.
docker images
Java environments generate images based on Linux. To run a container based on the previously created image, from the directory where the Dockerfile is located, execute the following command. See (run command).
docker run --rm -p 9999:8080 <Docker image name>
Where:
--rm
Indicates that the container is deleted once it is shut down
-p 9999:8080
Indicates that the port 8080 (Tomcat default) of the container is exposed as 9999 on the host
<Docker image name>
Is the one created in the previous step
After successfully running this command, you can access the application's main object at http://localhost:9999/servlet/<Java package name>.<qualified object's name>.
.NET Framework (C#) environments generate images based on Windows. To run a container based on the previously created image, execute the following command from the directory where the Dockerfile is located.
docker run --rm -p 9999:80 <Docker image name>
Where:
--rm
Indicates that the container is deleted once it is shut down
-p 9999:80
Indicates that the port 80 (IIS default) of the container is exposed as 9999 on the host
<Docker image name>
Is the one created in the previous step
ERROR ( message:Cannot find requested collection element. )
Applied configuration changes to section "system.applicationHost/applicationPools" for "MACHINE/WEBROOT/APPHOST" at configuration commit path "MACHINE/WEBROOT/APPHOST"
After successfully running this command, you can access the application's main object at http://localhost:9999/<qualified object's name>.aspx.
.NET environments generate images based on Linux. To run a container based on the previously created image, execute the following command.
docker run --rm -p 9999:8080 -e ASPNETCORE_URLS="http://*:8080" <Docker image name>
Where:
--rm
Indicates that the container is deleted once it is shut down
-p 9999:8080
This binds port 8080 of the container to TCP port 9999 on all interfaces (address 0.0.0.0) on the host. See publish or export port.
-e ASPNETCORE_URLS
The parameter
-e ASPNETCORE_URLS
is required for .NET 8 as it specfies the host and port Docker uses for HTTP connections for ASP.NET Core.
<Docker image name>
Is the one created in the previous step
Default ASP.NET Core port changed its default. Check the official documentation.
So this will not work:
docker run --rm -it -p 8000:80 <my-app>
Since this breaking change there are some neccesary changes in the way the container is started. See recommended actions.
Two alternatives are:
1. Use the "entrypoint" option to override the default ENTRYPOINT of the image (at the dockerfile). Set the exposed port of the application.
docker run --rm -p <hostPort>:<ContainerPortPublished> --name <containerName> --entrypoint dotnet <imageName> bin/GxNetCoreStartup.dll <virtualPath> <localPath> <ContainerPortExposed>
GxNetCoreStartup.dll receives as parameter the virtualPath, LocalPath, and port.
Example: docker run --rm -p 81:8080 --name mycontainer --entrypoint dotnet user/test:3.0 bin/GxNetCoreStartup.dll testvp /app 8080
In this example the application will run at http://localhost:81/testvp/<webpanel>.aspx
2. Use the ASPNETCORE_URLS environment variable.
docker run --rm -p 9999:8080 -e ASPNETCORE_URLS="http://*:8080" <Docker image name>
Accesing a remote server
To access a remote database server using a non-fully-qualified hostname from the container, you may need to specify a DNS search prefix. For example, if the DataStore server name is 'SqlServerSrv,' and the fully qualified name is 'mycompany.local.SqlServerSrv,' you can specify the prefix as follows:
docker run --rm -p 9999:5000 -e ASPNETCORE_URLS="http://*:5000" --dns-search mycompany.local <Docker image name>
After successfully running this command, you can access the application's main object at http://localhost:9999/<qualified object's name>.aspx.
Having the application run in a virtual directory
In NET generator, you can execute:
docker run --rm -p <hostPort>:<ContainerPortPublished> --name <containerName> --entrypoint dotnet <imageName> bin/GxNetCoreStartup.dll <virtualPath> <localPath> <ContainerPortExposed>
- Using default Docker base images
- In the .NET Framework and
.NET generators, it is essential to ensure that you have an SSL certificate. If such a certificate is not available, it is advisable to avoid setting the Protocol specification property to HTTPS to prevent the generation of timeout messages.
- Sites are accessed via HTTP
Troubleshooting deployment to Docker Containers
Application Deployment MSBuild tasks
Yes, you can. You can change the default base image to be used by GeneXus in the Docker base image property. There you can set your own image and the Docker client will try to pull it from a registry if it's not available on your computer. Keep in mind that the image WebApp location property might also need to be changed.
You can generate the Dockerfile even without the 'Docker for Windows' requirement. For that purpose, use this feature and select the option to deploy to Docker as usual.
A warning will appear, 'warning: Dockerfile successfully created, but no docker image was generated because Docker client was not found.' in that case.
If you want to just create the package, use the "Only Package option" in GeneXus (or the Deploy to Docker MSBuild task). If you try to build the image and don't have the Docker engine up and running, you will get an error.