Building IBM Sterling Order Management Software Docker images

Sterling Order Management Software, Release 10.0 and later provides you sample scripts for building docker images from your runtime directory that you installed using your Sterling Order Management Software installer in the Docker install mode.

You can thereafter deploy the docker images by using the sample Kubernetes scripts to perform multi-node deployment on production servers, or by using the sample Docker Compose scripts to perform single-node integrated deployment on development environments.

The sample scripts that are provided to build images are fully externalized to support a lot of advanced image building options. However, if these options are insufficient for image building, you can modify the sample scripts as needed for your business.

Prerequisites

To build the docker images from Sterling Order Management Software 10.0 runtime, ensure to meet the following prerequisites:

Install Sterling Order Management Software, Release10.0 runtime by using Sterling Order Management Software 10.0 installers in Docker install mode.
Have access to outbound internet access to install the docker and pull images such as Centos and WebSphere Liberty.
Install Docker.
- If you want to install Docker on Centos operating system, refer to Install Docker CE for Centos.
  After the installation completes successfully, start the Docker and verify that the Docker is installed correctly.
- If you are setting up the developer toolkit environment on a Linux-based environment as a non-root user, add the user to the docker group. For more information, see Manage Docker as a non-root user.
For more information about Docker, see Get started with Docker.
If you are using MQ server for messaging, download the MQ client jars from your MQ installation and copy them to a new directory (<MQ_JARS_DIR>) so that during the docker image build process, these jars get added to the docker images to connect to MQ.
Note: This is mandatory, if you plan to use the images for setting up development environment using the Docker Compose scripts, or plan to use MQ while deploying on Production using Kubernetes scripts.
Install a zip or unzip utility.
Optional: If you have any customizations, install them on runtime before proceeding with image building.

Building docker images

After installing the Sterling Order Management Software 10.0 by using the installers in the Docker install mode, a runtime directory is created with the Sterling Order Management Software binaries and files. However, this runtime does not yet have any link to any database components. In place of the actual database details, the database parameters point to DUMMY values.

All docker image building scripts, including the Docker files are present in the <RT>/docker-samples/imagebuild directory.

Here, <RT> refers to the SSterling Order Management Software 10.0 runtime directory that is installed in the docker install mode.

To generate the docker images assuming all default options, go to the <RT>/docker-samples/imagebuild directory, and run the following command:

./generateImages.sh

The following docker images are generated on your local registry, as well as an optional tar.gz file copy of the image (in your runtime's parent directory, unless overridden).

om-base:10.0 - This is a base runtime image of the Sterling Order Management Software runtime with all the required components for Sterling Order Management Software development and testing.
om-agent:10.0 - This is a light-weight runtime image of the Sterling Order Management Software runtime with only those components that are required for running the agents or integration servers, and installing the database components, including running the CDT.
om-app:10.0 - This is essentially a WebSphere Liberty application server image with the Sterling Order Management Software EAR added. Starting this image automatically deploys and starts all the installed Sterling Order Management Software suite of applications.

Advanced image building options

The generateImages.sh script is a versatile script that provides many advanced image building options assuming the default values for such options, in case you are not looking for the advanced usage.

The following table describes the arguments that can be passed to the script, their default application-provided values that are assumed, if any, if not passed, and its details.

Argument	Default value	Description
`--MODE`	all	The mode to generate images. The supported values are: base – Generates the base runtime image. agent – Generates the agent runtime image. app – Generates the application server image. all – Generates all the images.
`--EXPORT`	true	Whether to export the `tar.gz` image files. The supported values are, true \| false
`--EXPORT_DIR`	<RT>/.. (runtime's parent directory)	The directory to which the `tar.gz` image files are exported.
`--MQ_JARS_DIR`		The directory where all MQ client jars are picked from. For more information, see Adding IBM MQ client jars to the generated image.
`--SKIP_MQ_CHECK`	false	Whether to pause the script, if --MQ_JARS_DIR is not passed or found. This is useful when the script is run as part of CI or automation. The supported values are, true \| false.
`--SKIP_BUILDEAR`	false	If the value is passed as true and if the EAR file is present, the EAR building is skipped. The supported values are, true \| false.
`--BASE_REPO`	om-base	The repository name of base runtime image.
`--AGENT_REPO`	om-agent	The repository name of light-weight agent runtime image.
`--APP_REPO`	om-app	The repository name of application server image.
`--OM_TAG`	10.0	The tag name for all images.
`--BASE_TAG`		The tag name of the base image. If not passed, defaults to OM_TAG.
`--AGENT_TAG`		The tag name of agent image. If not passed, defaults to OM_TAG.
`--APP_TAG`		The tag name of app image. If not passed, defaults to OM_TAG.
`--BASE_DF`	./Dockerfile.om-base	The docker file to build the base runtime image.
`--AGENT_DF`	./Dockerfile.om-agent	The docker file to build light-weight agent runtime image.
`--APP_DF`	./Dockerfile.om-app	The docker file to build application server image.
`--WAR_FILES`	All installed apps	The list of war codes of all the applications that needs to be deployed. If all the Sterling Order Management Software-supported applications are installed, this value is assumed as smcfs, sma, sbc, isccs, wsc, and sfs. If all the applications need not be deployed, pass only the required codes. Do not pass code for any application that is not installed.
`--DEV_MODE`	true	Whether to build the EAR in the development mode. The supported values are, true \| false.
`--DB_SCHEMA_OWNER`	OMDB	The database schema name that can be overridden during deployment.
`--DB_DATASOURCE`	jdbc/OMDS	The datasource name used during deployment.
`--DPM`		Override the database property management. Default value does not exist. If not passed,this is not overridden. The supported values are, true \| false.
`--MQ_VER`	8_0	The MQ version of the downloaded MQ client jars.

Image build examples of advanced usage

Some examples of usage of the script with advanced options are as follows:

To build only the application server image with Application Console, Sterling Business Center, System Management Administrator, and Commerce Call Center, with devmode turned off, without exporting the tar.gz image files, and saving the image as xyzcorp-om-app:v10, run the following command:
```
./generateImages.sh --MODE=app --WAR_FILES=smcfs,sma,sbc,isccs --DEV_MODE=false --EXPORT=false --APP_REPO=xyzcorp-om-app --APP_TAG=v10
```
To build only the agent runtime image, exporting the tar.gz image files, saving the image as pqrcorp-om-agent:10.0, using the docker file /opt/dockerfiles/Dockerfile.agent, run the following command:
```
./generateImages.sh --MODE=agent --AGENT_REPO=pqrcorp-om-agent --AGENT_DF=/opt/dockerfiles/Dockerfile.agent
```
In addition to the pqrcorp-om-agent:10.0 image, a tar file <RT>/../om-agent_10.0.tar.gz is created.
To build all the three images, using tag v10 for all the images, exporting the tar.gz image files to the /opt/dockertar directory, creating an application image with only Sterling Store application, and using the docker file /opt/dockerfiles/Dockerfile.base to build the base runtime image, run the following command:
```
./generateImages.sh --OM_TAG=v10 --EXPORT_DIR=/opt/dockertar --WAR_FILES=wsc --BASE_DF=/opt/dockerfiles/Dockerfile.base
```

Adding IBM MQ client jars to the generated image

When you run the generateImages.sh script for the first time without passing the --MQ_JARS_DIR option, the script pauses with a warning prompting you to pass the option with the value of the directory where all your required IBM MQ client jars are downloaded. If you do not intend to use IBM MQ as part of the single or multi-node deployment, ignore this warning and proceed. However, it is recommended that you download the requisite jars and copy them to a directory and pass that as the --MQ_JARS_DIR argument to the script.

For MQ 8, the client jars that are required (but may not be limited to) includes com.ibm.mq.jar, com.ibm.mq.headers.jar, com.ibm.mqjms.jar, com.ibm.mq.jmqi.jar, jms.jar, providerutil.jar, and fscontext.jar. Download these jars from your MQ installation directory to a local download directory, and pass the argument --MQ_JARS_DIR=<Download directory> to the generateImages.sh script.

If you do not have access to your MQ installation directory, alternately try downloading the jars from MQ docker image (works for MQ 8 image) by running the following commands:

docker pull ibmcom/mq:8
docker run -d --name mq8_temp ibmcom/mq:8
cd <download_directory>
docker cp mq8_temp:/opt/mqm/java/lib/<jar_name>. Ensure that you run this command for each jar that are mentioned in the earlier paragraph.

For the first time, after passing the --MQ_JARS_DIR=<Download directory> option to the generateImages.sh script, the MQ client jars are installed as third-party jars in the runtime. Thereafter, you need not pass this option every time you run the generateImages.sh script.

Note: If you have added or modified the MQ Jars present in the <Download directory>, make sure that you delete the <RT>/jar/mq directory before running the generateImages.sh script.

Deployment

As already discussed, the images built using the scripts can be deployed using Kubernetes scripts to perform multi-node deployment on production servers or using Docker Compose scripts to perform single-node integrated deployment on development environments.

For multi-node deployment on production servers using Kubernetes scripts, you need the om-agent and om-app images and the scripts under <RT>/docker-samples/kubernetes directory. For more information about deployment using Kubernetes scripts, see Deploying IBM Sterling Order Management Software Docker images on a Kubernetes cluster.
For the single node integrated deployment on development environments by using Docker compose scripts, you need om-base and om-app images and the scripts under <RT>/docker-samples/compose directory. For more information about integrated deployment on development environments, see Docker-based developer toolkit environment.

Note: While generating the images, if you have overridden one or more default application-provided values of the arguments, you may need to make similar changes in the Docker Compose and Kubernetes scripts for them to work with the generated images.

Building a continuous integration pipeline for Sterling Order Management Software docker image build

System Integrators can build a continuous integration pipeline using tools such as Jenkins to prepare an automated Sterling Order Management Software image build process. The following figure illustrates the various constituents of such a pipeline.

Installation by using the Sterling Order Management Software Installer need not be automated as part of the pipeline for first time setup. This can be a one-time setup which creates the Sterling Order Management Software runtime first time. In a steady state, the following processes can be automated as Jenkins tasks to build a complete CI/CD pipeline:

Building and installing the customization package – Check out the customization source from GitHub or any source control repository that hosts all the customization files that are checked in by the developers. Build and install the customization package from this source to the Sterling Order Management Software runtime.
Installing Fix Packs – Install any Sterling Order Management Software fix packs to the Sterling Order Management Software runtime.
Building the docker images – As mentioned in this topic, running the generateImages script with the required options builds the necessary images for further deployment.
Push the images to docker registry - Customers can maintain a docker registry and push the generated images from the local registry to docker registry.

After the images are pushed to the customer's registry, the customer developers can pull them locally and set up or update their docker-based developer environment using the docker compose scripts. They can develop and test the customizations locally on this environment. When successfully completed, check them into their Sterling Order Management Software source control repository, there by completing their CI/CD pipeline.