Dockerizing the eiPlatform
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 Facilities of the eiPlatform
Several new facilities 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 allows for configuration settings to be defined at container build and/or run time. All eipServer.conf settings that are shipped with the product 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 complete list
Additional settings can also be added to the shipped settings following the same system environment variable convention if so desired.
- 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.
- 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:
- The eiPlatform WAR file (ie, eip.18R1.nn.war)
- The interface working directory (eip-root) which holds Interfaces configured using the eiConsole
- 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)
- 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-jre8-alpine # Set JVM memory ENV JAVA_OPTS="-Xms1g -Xmx3g" # Set eip-root config setting ENV PFISH_EIP_CONF_com_pilotfish_eip_configDirectory="/opt/pilotfish/eip-root" # Copy Working Directory contents COPY eip-root /opt/pilotfish/eip-root # Copy custom tomcat context.xml, see file for changes COPY eip.tomcat.context.xml /usr/local/tomcat/conf/context.xml # Copy in war file COPY eip.18R1.99.war /usr/local/tomcat/webapps/eip.war
- 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:18R1 .
- 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:18R1’.
- Other tag naming conventions can be used to suit your individual use-cases and needs.
- You should see the docker build the image.
- 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:18R1
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:18R1– Tag of image we want to run a container for
You will now see the container start up 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
- 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
- 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 common ones:
- 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
- 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).
- 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
- 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.
- 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.
A Word On Licensing and Restrictions
- Each eiPlatform docker container instance running in a production environment counts as one production eiPlatform instance for the purposes of licensing.
- 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.