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:
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).
The scripts provided with EntireX support the following three methods of building a Docker image and running the Docker container:
To copy the license and configuration files into the Docker image
Set your working directory to <install_dir>/EntireX/docker/Broker.
Create the TAR file containing all the necessary files with the following command:
./CreateEntireXBrokerTar.sh
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 |
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/
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.
To copy the license and configuration files into container, using default file names
Set your working directory to <install_dir>/EntireX/docker/Broker.
Create the TAR file containing all the necessary files with the following command:
./CreateEntireXBrokerTar.sh
Build the EntireX Broker image, for example:
docker build -t exx_broker_image_2 .
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.
To copy the license and configuration files into container, using custom file names
Set your working directory to <install_dir>/EntireX/docker/Broker.
Create the TAR file containing all the necessary files with the following command:
./CreateEntireXBrokerTar.sh
Build the EntireX Broker image, for example:
docker build -t exx_broker_image_3 .
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.
To verify the build
Show the image with command
docker images
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
Show the log:
docker logs -f exx_broker_container_1
Show the containers:
docker ps
Stop the container:
docker stop exx_broker_container_1
Delete the container:
docker rm exx_broker_container_1
Remove the image:
docker rmi exx_broker_image_1
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.