Dockerizing the eiPlatform

Overview

Docker is a container technology that allows for the packaging of an application along with its dependencies and related configuration to allow for simple cross-platform and cross-environment deployments. As the PilotFish eiPlatform promotes configuration over code, it is well-suited for container environments. eiPlatform docker images can be easily defined and utilized for rapid Interface development, testing, deployment, and ongoing maintenance. The instructions below demonstrate how to build a basic eiPlatform docker image and then run a container off of it. There are many further tweaks possible to customize and refine the created image however the examples below are aimed at the basic use-case.

Container Capabilities of the eiPlatform

Several new capabilities have been added to the software to allow it to operate better in container environments. One of the most visible is the ability to set the eiPlatform’s core configuration settings via system environment variables which allow for configuration settings to be defined at container build and/or run time. All eipServer.conf settings that are included by default define an associated, distinctive system environment variable that can be used to set the core values, ie:

• PFISH_EIP_CONF_com_pilotfish_eip_configDirectory – Interface top-level working directory
• PFISH_EIP_CONF_com_pilotfish_eip_logConfigFile – Log4J configuration file
• See eipServer.conf for the complete list

Additional settings can also be added to the shipped settings following the same system environment variable convention if so desired.

Instructions

1. 1. 1. Install docker locally (link to instructions)

         You will need docker installed on the host that you will be building the image and/or running the container(s) on.

      2. Assemble components of build context

         The docker build context can generally be thought of the files to be applied on top of the base image defined in the FROM Dockerfile declaration. For the eiPlatform this will be:

         1. The eiPlatform WAR file (ie, eip.war.hs.19R1.nn)
         2. The interface working directory (eip-root) which holds Interfaces configured using the eiConsole
         3. The eiPlatform License File (pflicense.key) – Available from support@pilotfishtechnology.com
         4. eip.tomcat.context.xml – A tomcat specific fixup to increase the static resource cache size (a good StackOverflow write-up of why this is included). The contents of this file are provided near the bottom of this page
      3. Define the Dockerfile

         The basic eiPlatform Dockerfile is quite simple, here we are using an image that includes Tomcat 8.5 with JRE 8 on top of Alpine Linux:

         FROM tomcat:8.5-jdk11
         
         # Set JVM memory
         ENV JAVA_OPTS="-Xms1g -Xmx3g"
         
         # Create eip-root and required subfolders
         RUN mkdir -p /opt/pilotfish/eip-root \
                      /opt/pilotfish/eip-root/formats \
                      /opt/pilotfish/eip-root/routes \
                      /opt/pilotfish/eip-root/interfaces 
         
         # Copy custom tomcat context.xml
         COPY eip.tomcat.context.xml /usr/local/tomcat/conf/context.xml
         
         # Copy in license file and set environmental variable
         COPY pflicense.key.19R1_TRIAL_KEY_expires_20191231  /opt/pilotfish/pflicense.key
         ENV PFISH_EIP_CONF_com_pilotfish_eip_license_file="/opt/pilotfish/pflicense.key"
         
         # Copy in war file
         COPY eip.war.hs.19R1.97 /usr/local/tomcat/webapps/eip.war
         
         # Copy eip-root and set environmental variable
         COPY eip-root /opt/pilotfish/eip-root
         ENV PFISH_EIP_CONF_com_pilotfish_eip_configDirectory="/opt/pilotfish/eip-root"
         

      4. Build the docker image

         Once the Dockerfile and build context are in place, its time to build the image (note the period at the end):

         docker build --tag eip:19R1 .

         • You should see the docker build the image.
           • If this is the first run you will notice it pulling down the base image layers from Docker Hub.
         • This command will also tag the image as ‘eip:19R1’.
           • Other tag naming conventions can be used to suit your individual use-cases and needs.
      5. Run a docker container from the image

         Now that you have the image, its time to run a container from it. Docker ‘containers’ are running instances of an image.

         docker run -it --rm --name eip1 -p 8181:8080 eip:19R1

         The `docker run` options and switches are described on Docker’s website,  here we are using the following:

         • -it – i=interactive, t=allocate a pseudo-tty (commonly used to start a docker on your local system, will allow things such as Ctrl-c to exit container)
         • --rm – Automatically remove container when it exits
         • --name – Name to give running container, though not required makes subsequent management with container easier
         • -p 8181:8080 – Publish container’s port 8080 as 8181 on the host system
         • eip:19R1 – Tag of image we want to run a container for

   You will now see the container startup and extract the eip.war file contents, at the end you should see a message indicating ‘org.apache.catalina.startup.Catalina.start Server startup in nnnn ms’ which indicates the application container has finished loading.

   Testing the Running Container

   1. 1. • Basic docker container testing:
           • Running `docker container list` will show you a list of running containers with some basic information
           • Running `docker exec -i -t eip1 /bin/bash` will give you a shell inside the eip1 container, from here you can navigate around the container’s filesystem to verify various aspects
      2. • eiPlatform testing:
           • If you’ve followed the instructions above, you can use a browser to open http://localhost:8181/eip/ where you will see an image along with a line indicating the eiPlatform version.
           • Verification and testing of interfaces would be specific to the particular interfaces deployed.

   Further Enhancements and Customization

   As indicated in the Overview section, the instructions presented are meant to stand up a basic eiPlatform docker instance. There are several areas where additional configuration and options can be introduced to better customize the end result, here are a couple of common ones:

   1. 1. • Dockerfile customization
           • Adding additional files/assets to the image
           • Setting the correct timezone.
             • The Alpine Linux docker image defaults to UTC. Refer to this link and other online resources for instructions on how to properly set the timezone.
           • Adjusting JAVA_OPTS settings such as memory allocated, garbage collection tweaking, etc
      2. • More use of system environmental variables
           • The above example included one build time environmental variable setting (PFISH_EIP_CONF_com_pilotfish_eip_configDirectory)  however this and other settings could have been set during the `docker run` command instead.
           • In addition to the pre-defined PFISH_* environmental variables, you can also incorporate system environmental variables into integration interfaces themselves to provide appropriate settings dependent on running environment (ie dev, QA or production).
      3. • Change logging config and location
           • By default eiPlatform logs are written to the logs/ subdirectory of the eip webapp, this can be changed to location such as /opt/pilotfish/logs by copying a custom log4j config XML file into the container and setting the PFISH_EIP_CONF_com_pilotfish_eip_logConfigFile environmental setting to point to it
      4. • Utilizing different docker command options
           • Both `docker build` and `docker run` have several additional options that can be set depending on your needs and version of docker, please refer to the online documentation for more information.
      5. • Container Orchestration
           • Once you have an application dockerized, the next step is to manage its lifecycle and its relationship with other containers. This is generally referred to as container orchestration, Kubernetes (k8s) is considered the current industry standard.

   eip.tomcat.context.xml file contents

   <Context>
       <Resources cachingAllowed="true" cacheMaxSize="20000" /> <!-- Increase cache from 10MB -->
   </Context>
   

   A Word On Licensing and Restrictions

   1. • Each eiPlatform docker container instance running in a production environment counts as one production eiPlatform instance for the purposes of licensing.
   2. • As the eiPlatform and other PilotFish software is proprietary and licensed software, no PilotFish intellectual property (“IP”), including but not limited to eiPlatform WAR file(s), installer(s) or docker images containing PilotFish IP can be published and/or pushed to docker registries and/or repositories that allow access to entities and/or parties outside of the licensed entity.