Building an EntireX RPC Server for XML/SOAP Docker Image

This document describes how to build an RPC Server for XML/SOAP Docker image and run the Docker container using scripts provided with EntireX. It covers the following topics:


Prerequisites

  • Operating system Linux

  • Docker installation 1.13.1 or compatible

  • Software AG EntireX installation containing the package EntireX > Core Files

Building and Running the RPC Server for XML/SOAP Image

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

Configuring with Modified Dockerfile

Start of instruction setTo copy license and configuration files into Docker container

  1. Set your working directory to <install_dir>/EntireX/docker/XmlSoapRpcServer.

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

    ./CreateEntireXXmlSoapRpcServerTar.sh
  3. Provide your installation and configuration files into the current working directory, for example:

    • myLicense.xml

    • myConfiguration

    • myWebServerConfiguration

    • myFirstMapping.xmm

    • mySecondMapping.xmm

    Note:
    All files are required if you are using this method.

  4. Update the Dockerfile, for example:

    # Possibility to add a valid license file already to the image instead of providing it during start up
    # e.g.:
    ADD myLicense.xml $EXXDIR/config/license.xml
      
    # Possibility to add the configuration file already to the image instead of providing it during start up
    # e.g.:
    ADD myConfiguration /configs/entirex.xmlrpcserver.properties
      
    # Possibility to add web server configuration file already to the image instead of providing it during start up
    # e.g.:
    ADD myWebServerConfiguration /configs/entirex.xmlrpcserver.configuration.xml
      
    # Possibility to add custom mapping file already to the image instead of providing it during start up
    # e.g.:
    ADD *.xmm /configs
  5. Build the server image:

    docker build -t exx_xml_soap_rpc_server_image_1 .

    In this case the Docker build command copies the configuration into the image.

  6. Start the container:

    docker run -d -e ACCEPT_EULA=Y --name exx_xml_soap_rpc_server_container_1 exx_xml_soap_rpc_server_image_1
  • Advantages
    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 have to build a new image before you rerun the container.

Configuring during Image Start, using Default File Names

Start of instruction setTo copy license, configuration and server implementation files into container, using default file names

  1. Set your working directory to <install_dir>/EntireX/docker/XmlSoapRpcServer.

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

    ./CreateEntireXXmlSoapRpcServerTar.sh
  3. Build the server image:

    docker build -t exx_xml_soap_rpc_server_image_2 .
  4. Provide your license, configuration and server implementation files with the default file names, for example:

    • <my-license-dir>/license.xml

    • <my-config-dir>/entirex.xmlrpcserver.properties

    • <my-config-dir>/entirex.xmlrpcserver.configuration.xml

    • <my-config-dir>/<myMapping>.xmm

    Note:
    All files are required if you are using this method.

    In this case the license and configuration files are mounted during startup.

  5. Start the container:

    docker run -d -e ACCEPT_EULA=Y 
                  -v <my-license-dir>:/licenses 
                  -v <my-config-dir>:/configs 
                  --name exx_xml_soap_rpc_server_container_2 exx_xml_soap_rpc_server_image_2
  • Advantages
    If the configuration changes, you do not need to rebuild the image; you only need to rerun the container.

  • Disadvantage
    The configuration, license and data files are mounted to the container. For troubleshooting, Software AG Support will require the image, configuration, license, data files and the command you entered.

Configuring during Image Start, using Custom File Names

Start of instruction setTo copy license, configuration and server implementation files into container, using custom file names

(Customer service implementation JAR file are provided in directory mounted to /data.)

  1. Set your working directory to <install_dir>/EntireX/docker/XmlSoapRpcServer.

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

    ./CreateEntireXXmlSoapRpcServerTar.sh
  3. Build the server image:

    docker build -t exx_xml_soap_rpc_server_image_3 .
  4. Provide your configuration files with your own file names, for example:

    • <my-license-dir>/myLicense

    • <my-config-dir>/myWebServerConfiguration

    • <my-config-dir>/myConfiguration

    • <my-config-dir>/myMapping.xmm

    Note:
    All files are required if you are using this method.

    In this case the license and configuration files are mounted during startup.

  5. Start the container:

    docker run -d 
                  -e ACCEPT_EULA=Y 
                  -e "EXX_LICENSE_KEY=myLicense.xml" 
                  -e "EXX_XML_SERVER_CONFIGURATION=myConfiguration" 
                  -e "EXX_XML_SERVER_MAPPING=myWebServerConfiguration" 
                  -v <my-license-dir>:/licenses 
                  -v <my-configuration-dir>:/configs 
                  --name exx_xml_soap_rpc_server_container_3 exx_xml_soap_rpc_server_image_3
  • Advantages
    If the configuration changes, you do not need to rebuild the image; you only need to rerun the container. You can choose your own file names.

  • Disadvantage
    The configuration, license and data files are mounted to the container. For troubleshooting, Software AG Support will require the image, configuration, license, data files and the command you entered.

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 -e ACCEPT_EULA=Y --name exx_xml_soap_rpc_server_container_1 exx_xml_soap_rpc_server_image_1
  3. Show the log:

    docker logs -f exx_xml_soap_rpc_server_container_1
  4. Show the containers:

    docker ps
  5. Stop the container:

    docker stop exx_xml_soap_rpc_server_container_1
  6. Delete the container:

    docker rm exx_xml_soap_rpc_server_container_1
  7. Remove the image:

    docker rmi exx_xml_soap_rpc_server_image_1

Healthcheck for RPC Server for XML/SOAP

The docker directory for RPC Server for XML/SOAP contains a script healthcheck.sh. Execution of this script pings the RPC server and returns the result of the ping command:

0  success
1  ping 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.