Building an ApplinX Docker Image

This document describes how to build an ApplinX Docker image and run the Docker container using scripts provided with ApplinX. It covers the following topics:

See also High Availability with Container Orchestration in the Administration documentation.

Prerequisites

  • Docker installation 1.13.1 or compatible.

  • Software AG ApplinX installation. The minimum requirement is ApplinX Server and Framework for JSP.

Building and Running the ApplinX Docker Image

The scripts provided with ApplinX support the following two methods of building a Docker image and running the Docker container.

Using a Modified Configuration

In this option a configuration file is used to define properties to connect to the host. You can set these properties in a Docker build command or in a Docker run as follows:

Start of instruction setTo use modified configuration files in the Docker build

  1. Set your working directory to <install_dir>/ApplinX/Docker.

  2. Create the TAR file containing all the necessary files with the following command:

    ./createApplinXDistributions.sh

  3. Provide your License file and put it in your license folder: <install_dir>/ApplinX/Docker/license/myLicense.xml.

  4. Update gx_updateAppConfig.xml file in folder <install_dir>/ApplinX/Docker/configuration with the properties to connect to the host.

  5. Build the ApplinX image with --build-arg USE_CONFIG_FILE=true, for example: 

    docker build --build-arg USE_CONFIG_FILE=true -t [Image Name] .

    With this method, the Docker build copies the configuration into the image; this file will be used to set the configuration of the ApplinX application. You then will need to map ports and set the credentials to connect to the ApplinX server. For example: 

    docker run -p 8080:8080  -p 2323:2323  --env USERNAME=<ApplinX server user> --env PASSWORD=<ApplinX server password> [Image Name] .

  • Advantages
    Configuration changes can be persistent; you can reuse the configuration when a new version or fix is to be built. The complete configuration is in the image. For troubleshooting, Software AG Support will require only the image and the command you entered.

  • Disadvantage
    If the configuration changes, you will need to build a new image and rerun the container.

Start of instruction setTo use modified configuration files in the Docker run

  1. Set your working directory to <install_dir>/ApplinX/Docker.

  2. Create the TAR file containing all the necessary files with the following command:

    ./createApplinXDistributions.sh

  3. Provide your License file and put it in your license folder: <install_dir>/ApplinX/Docker/license/myLicense.xml.

  4. Build the ApplinX image with, for example:

    docker build -t [Image Name] .

  5. Add to the docker run the USE_CONFIG_FILE=true property and specify the location of the configuration file (gx_updateAppConfig.xml) with -v prefix as follows: 

    docker run -v <local machine configuration folder>:/config -p 8080:8080  -p 2323:2323  --env USERNAME=<ApplinX server user> --env PASSWORD=<ApplinX server password> --env USE_CONFIG_FILE=true  [Image Name]

  • Advantages
    You can set for each container (instance of the image ) the specific configuration to connect to host.

Using a Customer Application File (GXAR File)

Note:
This is the correct way to create a complete Docker image with the ApplinX application. You can set properties in a Docker build command or in a Docker run as follows:

Start of instruction setTo use customer application file using a Docker build

  1. Set your working directory to <install_dir>/ApplinX/Docker.

  2. Create the TAR file containing all the necessary files with the following command:

    ./createApplinXDistributions.sh

  3. Provide your License file and put it in your license folder: <install_dir>/ApplinX/Docker/license/myLicense.xml.

  4. Provide your application GXAR file and put it in the data folder: <install_dir>/ApplinX/Docker/data/yourApplication.gxar.

  5. Build the ApplinX image, for example:

    docker build --build-arg GXAR_NAME_ARG=<yourApplication[.gxar]> -t [Image Name] .

    With this method, the Docker build copies the application into the image. You will need to map your ApplinX ports and set the credentials to connect to the ApplinX server during startup, for example: 

    docker run -p 8080:8080 -p 2323:2323 --env USERNAME=<ApplinX server user> --env PASSWORD=<ApplinX server password> [Image Name]

  • Advantages
    You can provide your application file; this file will be added to the image. For troubleshooting, Software AG Support will require only the image and the command you entered.

  • Disadvantage
    If you want to connect to another ApplinX application, you will need to build a new image and rerun the container.

Start of instruction setTo use customer application file using a Docker run

  1. Set your working directory to <install_dir>/ApplinX/Docker.

  2. Create the TAR file containing all the necessary files with the following command:

    ./createApplinXDistributions.sh

  3. Provide your License file and put it in your license folder: <install_dir>/ApplinX/Docker/license/myLicense.xml.

  4. Build the ApplinX image, for example:

    docker build  -t [Image Name] .

  5. Add to the Docker run the ApplinX GXAR file and its location (you also need to map the open ports and the ApplinX server credentials):

    docker run -v <local location of gxar file>:/data --env GXAR_NAME_ARG=<the name of the gxar file>[.gxar] -p 8080:8080 -p 2323:2323 --env USERNAME=<ApplinX server user> --env PASSWORD=<ApplinX server password> [Image Name]

  • Advantages
    You can set for each container (instance of the image) the specific ApplinX application to connect to host.

General Notes

  • If the Docker container wasn't defined correctly and there is a need to make some changes in the configuration, you can use an ApplinX Designer to connect to the ApplinX server through the port defined to it (the default is 2323). Then you can open the ApplinX application and make the needed changes. Those changes will be saved in the container and the container will become functional.

  • In the Docker run you can also provide local license files and configuration files by mapping them to the image specific folders as follows: 

    docker run -v <user_dir>/MyLicense:/license -v <user_dir>/MyConfig:/config -p 8080:8080 -p 2323:2323 [Image Name]

  • You can change/add configuration files and they will be added to the image when you run the Docker build:

    • <install_dir>/ApplinX/Docker/configuration/gx_updateAppConfig.xml

    • <install_dir>/ApplinX/Docker/configuration/gx_appConfig.xml

    • <install_dir>/ApplinX/Docker/configuration/gx_clientConfig.xml

    • <install_dir>/ApplinX/Docker/configuration/gx_keyboardMappings.xml

  • You can change the name of the imported ApplinX application by setting the APP_NAME_ARG property (the default name is DockerApplication).

  • In the Docker run phase, we need to connect to the ApplinX server in order to import the ApplinX application. For this you need to supply the ApplinX server credentials

    either in the Docker build phase:

    docker build --build-arg USERNAME_ARG=<ApplinX server user> --build-arg PASSWORD_ARG=<ApplinX server password>

    or in the Docker run:

    docker run  --env USERNAME=<ApplinX server user> --env PASSWORD=<ApplinX server password>

Verifying the Build

Start of instruction setTo verify the build

  1. Show the image with command

    docker images

  2. Start the docker image to be verified as described above, for example:

    docker run -d -p 8080:8080 -p 2380:2380 --name applinx_container_1 applinx_image_1

  3. Show the log:

    docker logs -f applinx_container_1

  4. Show the containers:

    docker ps

  5. Stop the container:

    docker stop applinx_container_1

  6. Delete the container:

    docker rm applinx_container_1

  7. Remove the image:

    docker rmi applinx_image_1

Healthcheck for the ApplinX Docker Image

The docker directory contains a script healthcheck.sh. Execution of this script pings the APX server and returns the result of the ping command:

0  success
1  failure

In the Docker context, this healthcheck.sh is put into the Docker container and enabled by setting the HEALTHCHECK instruction in the Dockerfile.

You can also use the healthcheck.sh script in the context of an orchestration tool (e.g. Kubernetes) to enable healthcheck functionality.

End-to-End Healthcheck for Natural for Linux and Clound

A typical installation of ApplinX connecting to Natural on a Linux host consists of the following:

  • Tomcat serving web page of the ApplinX Framework (or other web container such as JBoss, WebSphere, WebLogic)

  • ApplinX server

  • ApplinX daemon that checks the authentication of users

  • Natural-APX executable

  • Adabas (or another database)

ApplinX provides an end-to-end healthcheck for Natural for Linux and Cloud that identifies the point of failure. Two approaches are provided:

Command Line inside the Docker Container

Start of instruction setTo perform an end-to-end healthcheck using the command line

  • Call the script /opt/softwareag/natuxhealthcheck.sh with the required parameters.

    Option Description
    --help Show help for this utility
    -s <url> The ApplinX server url to connect to. By default applinx://localhost:2323
    -u <username> Specify the username to connect to the host (as required by the Natural Open System hosts)
    -p <password> Specify the password to connect to the host (as required by the Natural Open System hosts)
    -d <dbId> ID of The Adabas DB that you wish to test
    -a <application> Specify the ApplinX application to use for host connectivity information.

    The return value of the script indicates the end-to-end test result:

    Response
    Code     		Output Message Meaning
      0 OK. All five elements seem to be OK and running.
     -1 The ApplinX web application is not available. The Web Framework is not installed or tomcat is not up.
     -2 The ApplinX server is not available. No connection to ApplinX server can be established.
     -3 The ApplinX daemon is not available. No connection possible between the ApplinX server and the daemon.
     -4 Natural is not available. the natapx binary is not installed / buffer pool is full.
     -5 Adabas is not available. Adabas (or the back-end DB) is not available.
     -6 No username was specified.  
     -7 An invalid DB ID was specified.  
     -8 Invalid username or password.  
     -9 The healthcheck functionality is supported with Natural version 9.1.2 and above. To use this functionality, upgrade your Natural installation accordingly.  
    -10 One of the parameters is missing.  
    -11 Unexpected error.  

Healthcheck URL

Start of instruction setTo perform an end-to-end healthcheck using a URL

  • Enter the following:

    http://<host>:<port>/ApplinX/healthcheck?check_db=<db_id>&username=<username>&password=<password>

    Provide appropriate values for host, port, DB ID, user and password.

    The HTTP status indicates the result of the end-to-end test:

    HTTP
    Status     		Message Meaning
    200 OK. All five elements appear to be OK and running.
    403 No username was specified.  
    Invalid username or password  
    404 The ApplinX web application is not available. The Web Framework is not installed.
    503 The ApplinX server is not available. No connection to applinx server can be established.
    500 The ApplinX daemon is not available. No connection possible between the ApplinX server and the daemon.
    An invalid DB ID was specified.  
    Unexpected error.  
    501 Natural is not available. The natapx binary is not installed / buffer pool is full.
    Application misconfigured.  
    507 Adabas is not available Adabas (or the back-end DB) is not avalable.