Customizing certified containers

You can customize Sterling Order Management System Software either by using the om-base image or the Integrated Developer Toolkit.

Attention: Starting 8 March 2024 (10.0.2403.0) release, when customizing images, you no longer need to apply the --privileged flag, for Podman commands. For Docker, continue using the --privileged flag, until further notice.

Before you begin

  • If you want a later version than the version that is present in the container, ensure to install the most recent fix pack.
  • Mount the required logs or volumes that you may want to browse.

Preparing the customization runtime

By using the Integrated Developer Toolkit
You can use the Integrated Developer Toolkit for developing and applying customizations seamlessly.

When you set up the Integrated Developer Toolkit a container with om-runtime name is created, which you can use for generating custom images.

For more information about setting up the Integrated Development Toolkit, see Setting up the Integrated Development Toolkit.

By using the customization runtime

Ensure that the Docker or Podman is installed on the host machine and ensure that the user has appropriate permissions to run Docker or Podman commands. Also, ensure that the om-base image is pulled into the local Docker repository.

To prepare the customized runtime, complete the following steps:
  1. From the base image, create a custom runtime container with a shared directory, which is mounted from the host file system.
    Run the following Docker or Podman commands:
    • For Docker,
      docker volume create <oci-storage-name>
docker run -e LICENSE=accept -e LANG --privileged -v <oci-storage-name>:/images \
    -v <docker volume or host path>:/opt/ssfs/shared -it --name <container name> <image> bash
    • For Podman,
      sudo podman volume create <oci-storage-name>
sudo podman run -e LICENSE=accept -e LANG --privileged -v <oci-storage-name>:/images \
    -v <docker volume or host path>:/opt/ssfs/shared -it --name <container name> <image> bash
    For example, 
    docker volume create oms-images
docker run -e LICENSE=accept -e LANG --privileged -v oms-images:/images \
    -v /path/to/oms-shared:/opt/ssfs/shared -it --name om-cust-container cp.icr.io/cp/ibm-oms-<edition>/om-base:10.0.0.21-amd64

    After the command runs successfully, a container gets created and you are directed to the shell environment of the container.

    Here,
    • <oci-storage-name> - refers to the container volume that can be used for storage by buildah.
    • <docker volume or host path> - is an optional parameter that refers to the file system directory path or a docker volume that is mapped and shared with the container. The corresponding container path is /opt/ssfs/shared.
    • <container name> - refers to the name of the container.
    • <image> - refers to the om-base image. For example, cp.icr.io/cp/ibm-oms-<edition>/om-base:<image tag>.
    Note:
    • The application licenses are present in the /licenses directory within the image.
    • In case you exit from the shell environment of the container and want to again enter the shell environment of the container, run the following command:
      • For Docker,

        docker start <container name> && docker exec -it <container name> bash

      • For Podman,

        sudo podman start -a <container name>

    • It is recommended that you generate a new om-base image from the customized runtime so that the same om-base image can be used for developing further customizations.
  2. You are now inside the container shell.
    Note:
    • If you are using an image from fix pack 10.0.0.26, 10.0.0.29, or 10.0.2206.0, ensure to re-apply the appropriate fix pack in order to get the fix pack factory setup files.
    • Before providing the database details for the customization runtime, ensure that the database schema is created.
    • If you are customizing Sterling Order Management System Software beyond generating images, ensure to update the sandbox.cfg properties and other applicable properties.
    • Navigate to <runtime>/bin and run the ./setupfiles.sh command to ensure the changes are updated.
  3. Enable OIDC support by adding the following additional property to the /opt/ssfs/runtime/properties/sandbox file: 
    ENABLE_IBMID_AUTHENTICATION=true
  4. Configure the database properties.
    Multischema mode

    If you want to configure your database (Oracle, Db2, or PostgreSQL) with multischema, see Transforming certified containers for multischema. Then, configure the properties as explained in the following tables for the database that you are using. The Jdbc schema, URL, user, and password must be metadata information of multischema.

    Single schema mode

    • If you are using Db2, complete the following steps:
      Note: By default, the base runtime contains Db2 drivers.
      1. Configure the database connectivity by updating system_overrides.properties.
      2. Go to the /opt/ssfs/runtime/properties folder. Create the system_overrides.properties file and add the following properties:
        Property Value
        jdbcService.db2Pool.dbvendor db2
        jdbcService.db2Pool.systemPool true
        jdbcService.db2Pool.url jdbc:db2://<db host>:<db port>/<db name>
        jdbcService.db2Pool.catalog <db name>
        jdbcService.db2Pool.dbname <db name>
        jdbcService.db2Pool.user <db user>
        jdbcService.db2Pool.password <db user pass>
        jdbcService.db2Pool.schema <db name>
        Note: It is recommended that you ensure none of the application or agents are running against the same database when you are performing any database-related operations from the customized runtime. For example, ./dbverify.sh.
    • If you are using Oracle DB, complete the following steps:
      1. Copy Oracle jar to the container.
      2. Browse to the <runtime>/bin folder and install the Oracle driver by running the following commands:
        • ./install3rdParty.sh <vendorName> <vendorVersion> -d <path to ojdbc8.jar> -targetJVM EVERY
        • ./install3rdParty.sh <vendorName> <vendorVersion> -j <path to ojdbc8.jar> -targetJVM EVERY
      3. Browse to the /opt/ssfs/runtime/properties folder.
      4. Add or modify the following properties of sandbox.cfg file.
        Property Value
        Database connection properties
        ORA_HOST <oracle host name>
        ORA_PORT <oracle port number>
        ORA_DATA <Oracle service name/SID>
        ORA_USER <oracle user name>
        ORA_PASS <oracle user password>
        DB_SCHEMA_OWNER The default schema or schema-owner for the provided login ID.
        Database transformation properties
        ORACLE true
        Note: Replace the existing property DB2=true.
        JDBC_DRIVER <complete path to ojdbc8.jar in runtime>
        DB_DRIVERS <complete path to ojdbc8.jar in runtime>
        ORACLE_NLS_LENGTH_SEMANTICS The type of length semantic to use for Oracle database for dbverify tool.

        The valid values are CHAR or BYTE. The default value is BYTE.
        JDBC_VENDOR oracle
        DB_VENDOR Oracle
        UI_DB_POOL oracleUIPool
        DB_POOL oraclePool
        ARCHIVE_DB_POOL oracleArchivePool

        For more information about the sandbox.cfg properties, see the Sandbox.cfg properties.

      5. Browse to the <runtime>/bin folder and run the ./setupfiles.sh command.
    • If you are using PostgreSQL database, complete the following steps:
      1. Download and copy PostgreSQL driver (postgresql-42.2.24.jar) to the container with the name postgresql.jar.
      2. Browse to the <runtime>/bin folder and install the PostgreSQL driver by running the following commands:
        • ./install3rdParty.sh <vendorName> <vendorVersion> -d <path to postgresql.jar> -targetJVM EVERY
        • ./install3rdParty.sh <vendorName> <vendorVersion> -j <path to postgresql.jar> -targetJVM EVERY
      3. Browse to the /opt/ssfs/runtime/properties folder.
      4. Add or modify the following properties of sandbox.cfg file.
        Property Value
        Database connection properties
        DB_HOST <PostgreSQL host name>
        DB_PORT <PostgreSQL port number>
        DB_DATA <PostgreSQL database name>
        DB_USER <PostgreSQL user name>
        DB_PASS <PostgreSQL user password>
        DB_SCHEMA_OWNER The default schema or schema-owner for the provided login ID.
        Database transformation properties
        POSTGRESQL true
        Note: Replace the existing property DB2=true.
        JDBC_DRIVER <complete path to postgresql.jar in runtime>
        DB_DRIVERS <complete path to postgresql.jar in runtime>
        DB_VENDOR postgresql
        UI_DB_POOL postgresqlPool
        DB_POOL postgresqlPool
        Note:
        • If you want to transform your certified containers to a new database type, setting up the database transformation properties are mandatory.
        • The Sterling Order Management System Software Operator injects database connection properties automatically during deployment. Therefore, if you are using the customization container only to generate custom images, setting up the database connection properties are optional.

        For more information about the sandbox.cfg properties, see the Sandbox.cfg properties.

      5. Browse to the <runtime>/bin folder and run the ./setupfiles.sh command.
  5. Verify that the database connection is established by completing the following steps:
    1. Go to <runtime>/bin
    2. Run ./dbverify.sh
  6. Load the base factory setup to load the factory setup data.
  7. Load the fix pack factory setup. For more information, see Applying the latest fix pack by using base container image.

Applying customization

Importing customization package that is exported by using the Developer Toolkit environment
You can import custom extensions into the customization runtime to add custom extensions from a previously exported customization package by using the Developer Toolkit environment.

For for information about importing the customization package, see Importing custom extensions into the Developer Toolkit environment.

Manually updating your customization
To manually update your customization, complete the following steps:
Important: Maintain a backup of all the customization changes in the shared /opt/ssfs/shared directory so that your changes are not lost even if the container is lost.
  1. Edit your runtime similar to the regular runtime.

    For more information about customization, see Building and Deploying Extensions.

    You can share the files with the host machine by using the shared location, /opt/ssfs/shared.

  2. Rebuild the resources.jar and entities.jar.

    For more information about customization, see Building the database extensions.

Generating Javadoc

By default, the runtime does not contain Javadoc. To build Javadoc, browse to the /opt/ssfs/runtime/bin folder and run the following command:
./sci_ant.sh -f ../properties/xapiDeployer.xml alldocs

Additionally, starting from om-base image with tag 10.0.0.17 or later, the generate images script provides the ability to generate Javadoc and an image that can be deployed.

To generate the Javadoc image, navigate to /opt/ssfs/runtime/container-scripts/imagebuild folder, and run the following command:
./generateImages.sh --MODE=docs --EXPORT=false

This command generates a new image with the name om-app-docs. You can push this image to the cluster and deploy for accessing Javadoc. For more information about deploying multiple application images, see the Deploying smcfsdocs.

Known issue: If you are using Helm chart version 5.1.0, use the following URLs to access Javadoc:
  • To access the core Javadoc, suffix /yfscommon/core_javadocs/ in the default path. For example, https://<openshift-omsdocs-route>/smcfsdocs/yfscommon/core_javadocs/
  • To access the API Javadoc, suffix /yfscommon/api_javadocs/ in the default path. For example, https://<openshift-omsdocs-route>/smcfsdocs/yfscommon/api_javadocs/
  • To access the Entity Relationship Diagram (ERD), suffix /yfscommon/ERD/HTML/ in the default path. For example, https://<openshift-omsdocs-route>/smcfsdocs/yfscommon/ERD/HTML/

Loading the fix pack factory setup present in the om-base image or applying the latest fix pack

For instructions on how to load the fix pack factory setup that is present in the om-base image or to apply the latest fix pack, see Installing fix packs for Sterling Order Management System Software containers.

Applying language packs

The supported language packs are available as an archive at /var/opt/ssfs/LP.tgz. To apply language packs, run the following command:
tar -xf /var/opt/ssfs/LP.tgz -C /opt/ssfs/runtime

Important: You must apply language packs manually only on the images of FP23 or older. The images of FP26 and later come with language packs applied by default.

Generating custom images

Note: The following two URLs are whitelisted in the build box and you must allow your build machines to reach the repository for UBI8 and Liberty.
  • registry.access.redhat.com/ubi8/ubi
  • docker.io/ibmcom/websphere-liberty:23.0.0.12-kernel-java8-ibmjava-ubi
After you complete the customization in runtime container, you can regenerate the customized images by completing the following steps:
  1. Navigate to /opt/ssfs/runtime/container-scripts/imagebuild folder and run the following command:
    ./generateImages.sh --OM_TAG=<tagname> --EXPORT=false
    The following Sterling Order Management System Software docker images are generated in your local registry and an optional tar.gz file copy of the image (in the parent directory of your runtime, unless overridden) is present.
    • om-base:10.0 - This is a base runtime image of the Sterling Order Management System Software runtime with all the required components for Sterling Order Management System Software development and testing. When generating the base image, the following error may occur, if the packages are outdated and are not compatible for installation. To download the updated packages for installation, set the REFRESH_RPM_CACHE to true, when running the generateImages.sh script. 
      Error: 
 Problem 1: conflicting requests
  - nothing provides ...
 Problem 2: conflicting requests
  - nothing provides ....
      Note: The base image (om-base) is not a deployable container and is available to create customizations for your applications and agent features that are outside of the deployment cluster.
    • om-agent:10.0 - This is a light-weight runtime image of the Sterling Order Management System 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 System Software EAR added. Starting this image automatically deploys and starts all the installed Sterling Order Management System Software suite of applications.
      Note: The given command in step #1 generates om-app image with smcfs, sbc, sma, isccs, and wsc. For IBM® Sterling Store Engagement (Next-generation), pass an additional argument --WAR_FILES with isf and other WAR names as required. For more information about WAR_FILES, see Generate deployment patterns.
    Note: For deploying using Helm chart, only om-agent and om-app images are required to push to the registry.

    The om-app, om-agent, and om-base docker images are loaded to the local buildah repository. If you do not pass EXPORT=false, the *.tar files are created for all the three docker images and saved to the /opt/ssfs folder.

    To modify the build process, you can pass extra parameters to generateImages.sh. To learn about the available parameters, run the following command:
    ./generateImages.sh help

  2. To push the tar file to your cluster, complete the following steps:
    1. To make the *.tar available outside the container, copy the generated *.tar image files from /opt/ssfs to /opt/ssfs/shared folder.
    2. Move the om-app and om-agent image tar files to the master node where OpenShift® Container Platform is installed.
    To push your images directly from customization runtime, see Loading the custom images to OpenShift Container Platform.

For more information about the deployment patterns, generating differential images, advanced image build options, and combining the image build modes, see Advanced image build options.

For more information about instructions to install or upgrade the newly generated images by using the Sterling Order Management System Software Operator, see installing or upgrading Order Management Software by using Operator.

Customizing images in an airgap environment

Prerequisites

Before you customize the Sterling Order Management System Software images by using the generateImages.sh script, the UBI and WebSphere Liberty images must be available for the build to use these images.

You can store or load the images in several ways. Following are the two simple methods. The Liberty versions that are mentioned in the examples update over time. Ensure that you update these values to the supported versions. For more information about supported Liberty versions, see Software Product Compatibility Reports.

Method 1: Loading the images manually to the om-base container
  1. Save the images as archives as shown in the following example:
     # save as archives 
podman save -o ubi8.tar registry.access.redhat.com/ubi8/ubi
podman save -o liberty.tar docker.io/ibmcom/websphere-liberty:23.0.0.12-kernel-java8-ibmjava-ubi
  2. Copy the images to the om-base container.
     # copy images to the om-base container
podman cp ubi8.tar <your om-base container name>:<path inside the container>
podman cp liberty.tar <your om-base container name>:<path inside the container>
  3. Run the following commands.
    # exec to your container
# from inside your container
buildah pull docker-archive://<path inside the container>/ubi8.tar
buildah pull docker-archive://<path inside the container>/liberty.tar
  4. Verify that the images are present in the om-base container.
    # check to ensure the images are present
buildah images
Method 2: Setting up a local or private registry to store the images
  1. Set up a local registry.

    This is the registry that buildah pull the images from. Ensure that your om-base container has access to this registry.

  2. Mirror the following images to your local or private registry.
    • registry.access.redhat.com/ubi8/ubi
    • docker.io/ibmcom/websphere-liberty:23.0.0.12-kernel-java8-ibmjava-ubi
  3. Run the ./generateImages.sh script with the following flags set.
    • BUILDER_IMAGE: The ubi8 image from your local or private registry. It defaults to registry.access.redhat.com/ubi8/ubi.

      For example, --BUILDER_IMAGE=my.local.registry.com/ubi8/ubi:latest

    • LIBERTY_IMG: The liberty image that is to be used. It defaults to docker.io/ibmcom/websphere-liberty.

      For example, --LIBERTY_IMG=my.local.registry.com/websphere-liberty.

    • LIBERTY_TAG: The liberty tag that is to be used. It defaults to 23.0.0.12-kernel-java8-ibmjava-ubi.

      For example, --LIBERTY_TAG=23.0.0.12.

Generating images when duplicate WAR files are used

For images with tag 10.0.2306.0-amd64 and later, when there is only one group, the generatImages.sh results in an image that is named with the value that is specified in --APP_REPO, and the default is om-app. For more than one group, the images are named with the WAR names and are sorted alphabetically and hyphenated as shown in the following example.

  • Running generateImages.sh with --WAR_FILES=smcfs,sbc,sma:wsc,smcfs:isccs,smcfs:isf,smcfs generates four images: om-app-sbc-sma-smcfs, om-app-smcfs-wsc, om-app-isccs-smcfs, om-app-isf-smcfs. For images before 10.0.2306.0-amd64 tag, only om-app was generated.
  • Running generateImages.sh with --WAR_FILES=smcfs,sbc,sma,wsc,isccs,isf generates only om-app image.

While generating the images with more than two groups of WAR files, it does not generate the om-app image. By default, the image that is used for healthMonitor and restService is fetched from spec.image.oms.agentDefaultName (defaults to om-agent) and spec.image.oms.appDefaultName (defaults to om-app) respectively. These fields can be changed so that the healthMonitor and restService can fetch the right image to use. For more information, see Configuring image parameter.

Liberty profile by default in directory

For the images with tag 10.0.2306.0-amd64 and later, the application servers use Liberty profile by default in the directory structure. As a result, all the backend JAR files that were previously located in the /config/dropins/smcfs.ear directory are located in the /config/dropins/smcfs.ear/lib directory.

Ensure to update the configuration and references to reflect in the new directory structure, if needed. The Liberty profile can be turned off by setting the --LIBERTY-PROFILE=false when running the ./generateImages.sh script.