Building an EntireX Broker Image

This document describes how to build an EntireX Broker 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 packages

    • EntireX > Broker

    • EntireX > Adminstrating and Monitoring > Command Line Scripts

    See EntireX Installation Packages for full list.

    Note:
    The current version of EntireX Broker Docker container supports only stateless scenarios (no use of persistent store).

Building and Running the EntireX Broker 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 the license and configuration files into the Docker image

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

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

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

    File Req/
    Opt
    myLicense.xml R
    myEtbfile O
    myExxAppCert.pem O
    myExxAppKey.pem O
    myExxCACert.pem O
  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 a different attribute file already to the image instead of
    # providing it during start up
    # e.g.:
    ADD myEtbfile $EXXDIR/config/etb/$ETBIB/etbfile
     
    # Possibility to add certificates for security broker
    # e.g.:
    ADD *.pem $EXXDIR/config/etb/$ETBID/
  5. Build the EntireX Broker image, for example:

    docker build -t exx_broker_image_1 .

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

    docker run -d -p 2002:1971 -e ACCEPT_EULA=Y --name exx_broker_container_1 exx_broker_image_1
  • 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.

Configuring during Image Start, using Default File Names

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

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

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

    ./CreateEntireXBrokerTar.sh
  3. Build the EntireX Broker image, for example:

    docker build -t exx_broker_image_2 .
  4. Provide your configuration files with the default file names, for example:

    File Req/
    Opt
    license.xml R
    etbfile O
    exxAppCert.pem O
    exxAppKey.pem O
    exxCACert.pem O

    In this case the license and configuration files are mounted during startup. You will need to map your EntireX Broker ports during startup, for example:

    docker run -d -p 2004:1971 
                               -e ACCEPT_EULA=Y 
                               -v <my-license-dir>:/licenses
                               -v <my-config-dir>:/configs 
                               --name exx_broker_container_2 exx_broker_image_2
  • Advantages
    Configuration changes can be persistent; if the configuration changes, you only need to rerun the container.

  • Disadvantage
    The configuration is in the image and in the configuration files mounted to the container. For troubleshooting, Software AG Support will require an image, configuration files and the command you entered.

Configuring during Image Start, using Custom File Names

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

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

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

    ./CreateEntireXBrokerTar.sh
  3. Build the EntireX Broker image, for example:

    docker build -t exx_broker_image_3 .
  4. Provide your configuration files with the custom file names, for example:

    File Req/
    Opt
    <my-license-dir>/myLicense.xml R
    <my-config-dir>/myEtbfile O
    <my-config-dir>/myExxAppCert.pem O
    <my-config-dir>/myExxAppKey.pem O
    <my-config-dir>/myExxCACert.pem O

    In this case the license and configuration files are mounted during startup. License file and etbfile will be renamed to match EntireX Broker naming conventions. You will need to map your EntireX Broker ports during startup, for example:

    docker run -d -p 2004:1971
                  -e ACCEPT_EULA=Y 
                  -e "EXX_ATTRIBUTE=myEtbfile"
                  -e "EXX_LICENSE_KEY=myLicense.xml"
                  -e "EXX_KEY_FILE=myExxAppKey.pem"
                  -e "EXX_KEY_STORE=myExxAppCert.pem"
                  -e "EXX_TRUST_STORE=myExxCACert.pem"
                  -v <my-license-dir>:/licenses 
                  -v <my-config-dir>:/configs 
                  --name exx_broker_container_3 exx_broker_image_3
  • Advantages
    Configuration changes can be persistent; you are free to choose your own file names. If the configuration changes, you only need to to rerun the container.

  • Disadvantage
    The configuration is in the image and in the configuration files mounted to the container. For troubleshooting, Software AG Support will require an image, configuration 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 -p 2001:1971 -e ACCEPT_EULA=Y --name exx_broker_container_1 exx_broker_image_1
  3. Show the log:

    docker logs -f exx_broker_container_1
  4. Show the containers:

    docker ps
  5. Stop the container:

    docker stop exx_broker_container_1
  6. Delete the container:

    docker rm exx_broker_container_1
  7. Remove the image:

    docker rmi exx_broker_image_1

Healthcheck for EntireX Broker

The docker directory for EntireX Broker contains a script healthcheck.sh. Execution of this script pings the broker and returns the result of the ping command:

0  success
all other values  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.