Linux

Building a custom Docker image from a deployable package

You can build custom Docker images that include your custom code or custom configurations, and then share and deploy the new images.

HCL Commerce Version 9.1.14.0 or laterImportant: Beginning in HCL Commerce 9.1.14.0, application container images are built to be run as a non-root user by default. This change has the potential to break your custom deployment. Therefore, you must review this change and its potential impacts. For more information, see HCL Commerce container users and privileges.
Note: If you are working on a local runtime environment for testing, development, or debugging purposes, you might want to use a temporary method to quickly deploy changes to your local environment. For more information, see Updating applications inside running Docker containers.

Before you begin

  1. In a development environment, build customization packages (ts, store, search, xc) to include your custom code. For more information, see Building packages.
  2. Download the customization packages to your runtime environment.

About this task

The following procedure teaches you how to:
  1. Create a Dockerfile for each type of Docker image.
  2. Create a docker-compose.yml file that references the Dockerfiles to build the new images.
At the end this procedure, you will have directories and files that resemble the following structure:
+search
   ++Dockerfile
   ++CusDeploy
+store
   ++Dockerfile
   ++CusDeploy
+app
   ++Dockerfile
   ++CusDeploy
+web
   ++Dockerfile
+xc
   ++Dockerfile
   ++CusDeploy
+db
   ++Dockerfile
+docker-compose.yml

Procedure

  1. Create separate CusDeploy directories for each Docker image that you want to customize.
    For example,
    • /opt/WebSphere/db/CusDeploy
      Note: This is only applicable if you are running your database in a Docker container.
    • /opt/WebSphere/search/CusDeploy
    • /opt/WebSphere/store/CusDeploy
    • /opt/WebSphere/xc/CusDeploy
    • /opt/WebSphere/app/CusDeploy
    • /opt/WebSphere/web/CusDeploy
  2. Extract any customization packages that were created from the WCB utility to the appropriate directory.
    For example,
    • Extract wcbd-deploy-server-ts-app.zip to /opt/WebSphere/app/CusDeploy.
    • Extract wcbd-deploy-server-crs-app.zip to /opt/WebSphere/store/CusDeploy
    • Extract wcbd-deploy-server-search-app.zip to /opt/WebSphere/search/CusDeploy
    • Extract wcbd-deploy-server-xc-app.zip to /opt/WebSphere/xc/CusDeploy
    For more information about building packages, see Building packages.
  3. Complete the following steps to create or update a Dockerfile to build a new search-app Docker image.
    1. Create a Dockerfile in your search directory.
      For example, /opt/WebSphere/search/Dockerfile
    2. Add the following text to the Dockerfile.
      HCL Commerce Version 9.1.14.0 or later
      FROM <Docker_registry>/commerce/search-app:<source_image_tag>
      HEALTHCHECK CMD curl -f http://localhost:3737
      COPY --chown=comuser:comuser CusDeploy /SETUP/Cus
      RUN /SETUP/bin/applyCustomization.sh
      <optional_commands>
      For releases of HCL Commerce 9.1.0.0 to 9.1.13.0:
      FROM <Docker_registry>/commerce/search-app:<source_image_tag>
      HEALTHCHECK CMD curl -f http://localhost:3737
      COPY CusDeploy /SETUP/Cus
      RUN /SETUP/bin/applyCustomization.sh
      <optional_commands>
      Note: The HEALTHCHECK instruction checks the health of the application when the container is running. As the number of deployed containers grow, you might have to increase the HEALTHCHECK interval to avoid failures on check.
      Docker_registry
      The Docker registry URL where the source image is located.
      source_image_name
      The name of the source image. For example, ts-app, ts-web, crs-app, search-app, xc-app.
      source_image_tag
      The tag of the source image that you want to use.
      optional_commands
      (Optional) You can specify other commands to configure the application inside the Docker image. This can include using Run Engine commands or creating container start up scripts. For example, you can use Run Engine commands to set the data source so that the application can connect to your database.
      • The FROM argument specifies which base Docker image to update.
      • The RUN argument references a shell script that instructs how to apply the customization package to the source image.
  4. Complete the following steps to create or update a Dockerfile to build a new crs-app (Store) Docker image.
    1. Create a Dockerfile in your store directory.
      For example, /opt/WebSphere/store/Dockerfile
    2. Add the following text to the Dockerfile.
      HCL Commerce Version 9.1.14.0 or later
      FROM <Docker_registry>/commerce/crs-app:<source_image_tag> 
      USER root 
      # Using dnf in Ubi8 for package installation 
      RUN dnf install -y nc && dnf clean all 
      USER comuser 
      HEALTHCHECK CMD nc localhost 8080 < /dev/null 
      COPY --chown=comuser:comuser CusDeploy /SETUP/Cus 
      RUN /SETUP/bin/applyCustomization.sh 
      <optional_commands>
      For releases of HCL Commerce 9.1.0.0 to 9.1.13.0:
      FROM <Docker_registry>/commerce/crs-app:<source_image_tag>
      # Using yum in RHEL/CentOS for package installation
      RUN yum install -y nc && yum clean all
      HEALTHCHECK CMD nc localhost 8080 < /dev/null
      COPY CusDeploy /SETUP/Cus
      RUN /SETUP/bin/applyCustomization.sh
      <optional_commands>
  5. Complete the following steps to create or update a Dockerfile to build a new ts-app Transaction server Docker container image.
    1. Create a Dockerfile in your app directory.
      For example, /opt/WebSphere/app/Dockerfile
    2. Add the following text to the Dockerfile.
      HCL Commerce Version 9.1.14.0 or later
      FROM Docker_registry/commerce/ts-app:source_image_tag
      USER root 
      # Using dnf in UBI8 for package installation 
      RUN dnf install -y nc && dnf clean all 
      USER comuser 
      HEALTHCHECK --retries=10 CMD nc localhost 5080 < /dev/nul 
      COPY --chown=comuser:comuser CusDeploy /SETUP/Cus 
      RUN /SETUP/bin/applyCustomization.sh 
      optional_commands
      For releases of HCL Commerce 9.1.0.0 to 9.1.13.0:
      FROM Docker_registry/commerce/ts-app:source_image_tag
      RUN yum install -y nc && yum clean all
      HEALTHCHECK --retries=10 CMD nc localhost 5080 < /dev/nul
      COPY CusDeploy /SETUP/Cus
      RUN /SETUP/bin/applyCustomization.sh
      optional_commands
  6. Complete the following steps to create or update a Dockerfile to build a new xc-app (Customization) Docker image.
    1. Create a Dockerfile in your xc directory.
      For example, /opt/WebSphere/xc/Dockerfile
    2. Add the following text to the Dockerfile.
      HCL Commerce Version 9.1.14.0 or later
      FROM Docker_registry/commerce/xc-app:source_image_tag
      USER root 
      # Using dnf in UBI8 for package installation 
      RUN dnf install -y nc && dnf clean all 
      USER comuser 
      COPY --chown=comuser:comuser CusDeploy /SETUP/Cus 
      RUN /SETUP/bin/applyCustomization.sh 
      optional_commands 
      For releases of HCL Commerce 9.1.0.0 to 9.1.13.0:
      FROM  Docker_registry/commerce/xc-app:source_image_tag
      # Using yum in RHEL/CentOS for package installation
      RUN yum install -y nc && yum clean all
      COPY CusDeploy /SETUP/Cus
      RUN /SETUP/bin/applyCustomization.sh
      optional_commands
  7. Complete the following steps to create or update a Dockerfile to build a new ts-web (Web) Docker image.
    1. Create a Dockerfile in your web directory.
      For example, /opt/WebSphere/web/Dockerfile
    2. Add the following text to the Dockerfile.
      HCL Commerce Version 9.1.14.0 or later
      FROM Docker_registry/commerce/ts-web:source_image_tag 
      USER root 
      # Using dnf in UBI8 for package installation 
      RUN dnf install -y nc && dnf clean all 
      USER comuser 
      HEALTHCHECK --interval=10s CMD nc localhost 8000 < /dev/null 
      #If you are using a local store from HCL Commerce Version 8 uncomment the next line. 
      #COPY --chown=comuser:comuser localStoreStaticAsset/ /SETUP/Cus/ 
      optional_commands 
      For releases of HCL Commerce 9.1.0.0 to 9.1.13.0:
      FROM Docker_registry/commerce/ts-web:source_image_tag
      RUN yum install -y nc && yum clean all
      HEALTHCHECK --interval=10s CMD nc localhost 8000 < /dev/null
      #If you are using a local store from HCL Commerce Version 8 uncomment the next line.
      #COPY localStoreStaticAsset/ /SETUP/Cus/
      optional_commands
  8. Complete the following steps to create or update a Dockerfile to build a new ts-db (Database) Docker image.
    Note: This is only applicable if you are running your database in a Docker container.
    1. Create a Dockerfile in your db directory.
      For example, /opt/WebSphere/db/Dockerfile
    2. Add the following text to the Dockerfile.
      FROM  Docker_registry/commerce/ts-db:source_image_tag
      RUN yum install -y netcat && yum clean
      HEALTHCHECK --interval=20s CMD nc -z localhost 50000
      optional_commands
  9. Copy your existing docker-compose.yml file into the same directory that holds your Docker directories.
    For example, /opt/WebSphere/docker-compose.yml.
  10. Edit the docker-compose.yml file to add build and context parameters.
    For example,
      db:
        build:
          context: db
        image: <docker_registry>/commerce/ts-db:<tag>
        ...
    
      app:
        build:
          context: app
        image: <docker_registry>/commerce/ts-app:<tag>
        ...
    
      search:
        build:
          context: search
        image: <docker_registry>/commerce/search-app:<tag>
        ...
    
      store:
        build:
          context: store
        image: <docker_registry>/commerce/crs-app:<tag>
        ...
    
      web:
        build:
          context: web
        image: <docker_registry>/commerce/ts-web:<tag>
        ...
  11. Stop and remove the existing running containers.
    For example, you can run the following command:
    docker-compose -f docker-compose.yml rm
  12. Run the following command to build the new images.
    docker-compose -f docker-compose.yml build
    Note: If you want to build and then deploy the containers in one command, you can use
    docker-compose -f docker-compose.yml up --build -d