Customizing certified containers

You can customize Sterling Order Management Software by using the om-base docker image.

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.
    • If you are using om-base image with tag 10.0.0.17 or later, 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>
      • 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>
    • If you are using om-base image with tag earlier than 10.0.0.17, run the following Docker or Podman commands:
      • For Docker,
        docker volume create <oci-storage-name>
docker run -e LICENSE=accept --privileged -v <oci-storage-name>:/opt/ssfs/shared/oci-runtime \
    -v <docker volume or host path>:/opt/ssfs/shared -it --name <container name> <image>
      • For Podman,
        sudo podman volume create <oci-storage-name>
sudo podman run -e LICENSE=accept --privileged -v <oci-storage-name>:/opt/ssfs/shared/oci-runtime \
    -v <docker volume or host path>:/opt/ssfs/shared -it --name <container name> <image>
    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:10.0.0.17-amd64.
    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:
    • Before providing the database details for the customization runtime, ensure that the database schema is created.
    • If you are customizing Sterling Order Management 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. Configure the database properties.
    • 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 command:
        ./install3rdParty.sh <vendorName> <vendorVersion> -d <path to ojdbc8.jar> -targetJVM EVERY.
        Note: When you run the ./setupfile.sh command, the oracle driver entries in AGENTDynamicclasspath.cfg and APPDynamicclasspath.cfg do not get automatically updated. Add the following entries in AGENTDynamicclasspath.cfg.in and APPDynamicclasspath.cfg.in.
        • VENDOR_JAR=&INSTALL_DIR;<runtime relative path to ojdbc8.jar>
        • DB_JAR=&INSTALL_DIR;<runtime relative path to ojdbc8.jar>

        For example, &INSTALL_DIR;/dbjar/jdbc/ORACLE/ojdbc8.jar

      3. Browse to the /opt/ssfs/runtime/properties folder.
      4. Add or modify the following properties of sandbox.cfg file.
        Property Value
        ORACLE true
        Note: Replace the existing property DB2=true.
        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.
        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.
        DB_VENDOR oracle
        UI_DB_POOL oracleUIPool
        DB_POOL oracleUIPool
        ARCHIVE_DB_POOL oracleArchivePool

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

      5. Verify that the changes are updated. For this, browse to the <runtime>/bin folder and run the ./setupfiles.sh command.

  4. Verify that the connection to Oracle database is established. For this, go to <runtime>/bin and run ./dbverify.sh.

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 Readme file.

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 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

Generating custom images

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 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 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.

    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 make the *.tar available outside the container, copy the generated *.tar image files from /opt/ssfs to /opt/ssfs/shared folder.
  3. Move the om-app and om-agent image tar files to the master node where OpenShift Container platform is installed.

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.