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.

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

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

About this task

The following procedure teaches you how to:

Create a Dockerfile for each type of Docker image.
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

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
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.
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.
```
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.
  
  For more information about Run Engine commands, see Run Engine command framework.
  
  For more information about custom container start up scripts, see Docker container start up logic for HCL Commerce Version 9.1.
  - 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.

Complete the following steps to create or update a Dockerfile to build a new crs-app (Store) Docker image.

Create a Dockerfile in your store directory.
For example, /opt/WebSphere/store/Dockerfile

Add the following text to the Dockerfile.

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>

Complete the following steps to create or update a Dockerfile to build a new ts-app Transaction server Docker container image.

Create a Dockerfile in your app directory.
For example, /opt/WebSphere/app/Dockerfile

Add the following text to the Dockerfile.

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

Complete the following steps to create or update a Dockerfile to build a new xc-app (Customization) Docker image.

Create a Dockerfile in your xc directory.
For example, /opt/WebSphere/xc/Dockerfile

Add the following text to the Dockerfile.

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

Complete the following steps to create or update a Dockerfile to build a new ts-web (Web) Docker image.

Create a Dockerfile in your web directory.
For example, /opt/WebSphere/web/Dockerfile

Add the following text to the Dockerfile.

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

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
```
Copy your existing docker-compose.yml file into the same directory that holds your Docker directories.
For example, /opt/WebSphere/docker-compose.yml.

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

Stop and remove the existing running containers.
For example, you can run the following command:
```
docker-compose -f docker-compose.yml rm
```
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
```