Building Apama projects during the Docker build
Some Apama applications, particularly those developed using
Software AG Designer or those with custom plug-ins, require additional build steps when creating a Docker image, such as running the
engine_deploy tool (see also
Deploying a correlator). For those using the sample packaging kit to create base images from an installation, this can be done directly in a standard Dockerfile. For those using the official Docker Hub image, a second builder image can be used for project build steps. This is in order to keep the runtime image as small as possible. The builder image can be used as part of a Docker multi-stage build.
A typical multi-stage Dockerfile looks like this:
FROM buildbase as builder
COPY source /source
RUN buildstep
FROM runtimebase
COPY --from=builder /buildoutput /buildoutput
CMD ["/buildoutput"]
For a typical Software AG Designer-based Apama project, your Dockerfile looks something like this:
ARG APAMA_VERSION=version
ARG APAMA_BUILDER=store/softwareag/apama-builder:${APAMA_VERSION}
ARG APAMA_IMAGE=store/softwareag/apama-correlator:${APAMA_VERSION}
FROM ${APAMA_BUILDER} as builder
COPY --chown=sagadmin:sagadmin MyProject ${APAMA_WORK}/MyProject
RUN engine_deploy --outputDeployDir ${APAMA_WORK}/MyProject_deployed \
${APAMA_WORK}/MyProject
FROM ${APAMA_IMAGE}
COPY --from=builder --chown=sagadmin:sagadmin ${APAMA_WORK}/MyProject_deployed \
${APAMA_WORK}/MyProject_deployed
WORKDIR ${APAMA_WORK}
CMD ["correlator", "--config", "MyProject_deployed"]
In
Software AG Designer, you can add Docker support to your project as described in
Adding Docker support to Apama projects. When you do this, a Dockerfile similar to the one above is automatically created in the project. Therefore, a project with Docker support can be built into an image using the following command:
docker build MyProject
For most projects, the provided Dockerfile will be sufficient. If you have additional build steps (such as building custom plug-ins), you can add them to the Dockerfile in your project. If your project uses Digital Event Services, then you must ensure that your type repository is available at build time. If you check it out to a TypeRepository folder within your project, then the provided Dockerfile will work automatically. A default Dockerfile with the name Dockerfile.project is provided in the etc directory of your Apama installation. You can copy this file manually into the root of any project which can be deployed using the engine_deploy tool.
Also, note the use of build arguments in the Dockerfile. This allows you to use --build-arg to specify the name of an alternative builder or runtime image. If you want to use the automatically generated Dockerfile with your own image created from the packaging kit, you need to set the build arguments appropriately:
docker build -t appimage --build-arg APAMA_BUILDER=apamaimage
--build-arg APAMA_IMAGE=apamaimage MyProject
Alternatively, you can just change the version of Apama that is used from Docker Hub:
docker build -t appimage --build-arg APAMA_VERSION=version
Note:
Each time you import an Apama project from a previous version into the current version, you have to update the version in the Dockerfile, or you have to run docker build with the appropriate build arguments to override the version. Software AG Designer will warn you if your Dockerfile is not up to date with the current version.
The builder image provides the following additional tools:
engine_deploy - to convert a project (either from
Software AG Designer, or a collection of monitors created outside of
Software AG Designer) into a configuration directory which can be used to start a correlator. See also
Deploying a correlator.
The image also contains a Java compiler. It does not by default contain a C++ compiler. If you want to compile C++ code, then you need to install a C++ compiler as part of your build step using a multi-stage build. This is only included while you are building, not in the final image, as long as you do it in the build part of a multi-stage build.
ARG APAMA_BUILDER=store/softwareag/apama-builder:version
ARG APAMA_IMAGE=store/softwareag/apama-correlator:version
FROM ${APAMA_BUILDER} as builder
COPY --chown=sagadmin:sagadmin MyProject ${APAMA_WORK}/MyProject
RUN engine_deploy --outputDeployDir ${APAMA_WORK}/MyProject_deployed \
${APAMA_WORK}/MyProject
RUN yum install gcc make && make -C MyProject
FROM ${APAMA_IMAGE}
COPY --chown=sagadmin:sagadmin --from=builder \
${APAMA_WORK}/MyProject_deployed ${APAMA_WORK}/MyProject_deployed
COPY --chown=sagadmin:sagadmin --from=builder \
${APAMA_WORK}/MyProject/libMyLib.so ${APAMA_WORK}/lib/libMyLib.so
WORKDIR ${APAMA_WORK}
CMD ["correlator", "--config", "MyProject_deployed"]
The Queries sample (see
Apama samples for Docker) in the
samples/docker/application/Queries directory of your Apama installation demonstrates the use of multi-stage builds to create Docker images from
Software AG Designer projects.