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:

• Prerequisites

• Building and Running the ApplinX Docker Image

• Verifying the Build

• Healthcheck for the ApplinX Docker Image

• End-to-End Healthcheck for Natural for UNIX

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 three methods of building a Docker image and running the Docker container.

• Using the Default Configuration

• Using a Modified Configuration

• Using a Customer Application File

• Using Customer Configuration Folders

Using the Default Configuration

To use the default configuration

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

   This method uses the default configuration after the installation, for example:

   docker run -p 8080:8080 -p 2323:2323 [Image Name]

• Advantages
  The complete configuration is in the image. For troubleshooting, Software AG Support will require only the command you entered.

• Disadvantage
  The only thing you can change is the ApplinX port mapping.

Using a Modified Configuration

To use modified configuration files

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. Change your configuration files:

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

5. Build the ApplinX image, for example:

   docker build -t [Image Name] .

   With this method, the Docker build copies the configuration into the image. You will need to map your ApplinX ports during startup, for example:

   docker run -p 8080:8080 -p 2323:2323 [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.

Using a Customer Application File

To use customer application file

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] -t [Image Name] .

   With this method, the Docker build copies the configuration into the image. You will need to map your ApplinX ports during startup, for example:

   docker run -p 8080:8080 -p 2323:2323 [Image Name]

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

Using Customer Configuration Folders

To use customer configuration folders

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 folder, for example: <user_dir>/MyLicense.

4. Provide your configuration folder, for example: <user_dir>/MyConfig.

5. Build the ApplinX image, for example:

   docker build -t [Image Name] .

   With this method, the Docker build copies the configuration into the image. You will need to add your folders path during startup, for example:

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

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

Verifying the Build

To 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 UNIX

A typical installation of ApplinX connecting to Natural on a Unix 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 UNIX that identifies the point of failure. Two approaches are provided:

• Command Line inside the Docker Container

• Healthcheck URL

Command Line inside the Docker Container

To 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

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