Customizing images with om-base image

Customizing with the om-base image involves creating a custom runtime container, applying customizations related to APIs, databases, or the user interface, and modifying database properties as needed. The process of customization using the om-base image is also referred to as the customization runtime.

1. From the base image, create a custom runtime container with a shared directory, which is mounted from the host file system.
   1. Run the following Docker or Podman commands:

      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

      Podman

      sudo podman volume create <oci-storage-name>
      sudo podman run -e LICENSE=accept -e LANG -v <oci-storage-name>:/images \
          -v <docker volume or host path>:/opt/ssfs/shared -it --name <container name> <image> bash

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

      Docker 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 commands run successfully, a container is created and you are directed to the shell environment of the container.

      • 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.
      Note: To minimize the base image size, certain large directories and files in the runtime are compressed. These files are extracted when the container is created, which occurs when the entrypoint script is executed.

      Starting from version 10.0.2406.0 and later, if the Docker image is built using a Dockerfile from cp.icr.io/cp/ibm-oms-enterprise/om-base, run the following command to extract the required directories and files into the runtime.

      RUN tar -xzf /opt/ssfs/runtime/archive.tar.gz -C /opt/ssfs/runtime/ && rm -f /opt/ssfs/runtime/archive.tar.gz 

2. Review the following information before proceeding to next steps.
   • 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.
   • Ensure that the database schema is created before providing the database details for the customization runtime.
   • If you are customizing Sterling™ Order Management System Software beyond generating images, 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 property to the /opt/ssfs/runtime/properties/sandbox file. For more information, see Supporting OIDC provider login in Operator.

   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 containers for multischema. Then, configure the properties for the database that you are using. The Jdbc schema, URL, user, and password must be metadata information of multischema.

   Single schema mode

   Db2

   Complete the following steps if you are using Db2. 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.
   3. Create the system_overrides.properties file and add the Db2 properties. For more information, see Db2 properties.
   4. Ensure none of the applications or agents are running against the same database when you are performing any database-related operations from the customized runtime.

   Oracle

   Complete the following steps if you are using Oracle.

   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 Oracle properties in sandbox.cfg file. For more information, see Oracle properties.

      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.

   PostgreSQL

   1. Download and copy PostgreSQL driver that is 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 PostgreSQL properties in the sandbox.cfg file. For more information, see PostgreSQL properties.
      Note:

      • If you want to transform your 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 is 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 present in the om-base image or apply the latest fix pack. For more information, see Installing fix pack for Sterling Order Management System Software containers.
8. To apply any user interface customizations in the Sterling Business Center, see Customizing Sterling Business Center images.
9. Optional: By default, the runtime does not contain Javadoc. If you want to build Javadoc, run the following command.

   ./sci_ant.sh -f ../properties/xapiDeployer.xml alldocs

   For 10.0.0.17 or later om-base image, use generate images script to generate Javadoc and an image that can be deployed. 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.
10. Optional: Apply language packs manually only for the images of FP23 or older. The images of FP26 and later comes with language packs applied by default. The supported language packs are available as an archive at /var/opt/ssfs/LP.tgz.

    tar -xf /var/opt/ssfs/LP.tgz -C /opt/ssfs/runtime