HCL Commerce Version or later

Docker container start up logic for HCL Commerce Version or later

When you deploy a container from an HCL provided image, an Entrypoint.sh helper script determines the configurations to use while starting up the container. Review the following information to learn about what the helper script does, and how you can customize the configurations.

By understanding the start up process of these Docker containers, you can learn how to customize the configurations to meet your needs and integrate with your container infrastructure to support your production environment. This information is also important if you choose to build a continuous integration and continuous deployment (CI/CD) pipeline to streamline the deployment process. Your pipeline needs to be able to retrieve these environment configuration values and pass the values to each Docker container that is started.

Local Docker container start up help documents

You can access quick help documents on the machine where the Docker images are loaded. For more information, see Accessing Docker image Help. Continue reading to get a more comprehensive understanding of the start up logic and to learn how to customize your containers.

HCL Commerce default configurations

HCL provided Docker images have embedded default configurations so that you can quickly deploy a runtime environment by only making minimal changes to the Docker image. If you do not use the default Docker container host names or database information, then ensure that you pass in the necessary parameters during container start up. First, here are the default configuration values.
  • Each HCL Commerce Docker container is configured to use a specific host name and default certificate to connect to other containers. There is strict verification logic in place to check if the host name that is used in a request is the same as the SubjectAlternativeName in the certificate on the target container. If you deploy containers and specify different host names, then the connection fails unless you reconfigure the internal certificates.
    Docker image Default host name
    commerce/crs-app store
    commerce/search-app search
    commerce/xc-app xc
    commerce/ts-app app
    commerce/ts-web web
    Note: This assumes that you are running a Db2 Docker container.
    If you do not use the default host names from the table, then you need to update the SubjectAlternativeName in your certificates. For more information, see Managing certificates manually.
  • Default database configurations. The Docker images are preconfigured to connect to a database with the following credentials.
    Database parameters Value
    Database type (dbType) db2
    • For the Transaction server:
    • For the Search server:
    Database instance name (dbName) mall
    Database user (dbUser) wcs
    Database user password (dbUserPass) wcs1
    Database host (dbHost) db
    Database port (dbPort) 50000
    If you created a database instance with the default values, then you do not have to update the datasource configuration in the Docker images. You might want to use the default values in a local test environment, but for security reasons, you do not want to use the default values in a production environment. For information about changing the database connections in your images, see Configuring database connections in Docker images.

Docker start up flow diagram

The following diagram illustrates the underlying logic and commands that run when you start a container. HCL defines a unique /SETUP/bin/entrypoint.sh script as the Docker image ENTRYPOINT to specify start up commands and configurations. For more information about ENTRYPOINT, see Dockerfile ENTRYPOINT. The following diagram is a visual representation of the start up logic.
Image of Entrypoint.sh
  1. entrypoint.sh first checks for license acceptance. All containers require LICENSE=accept to be passed in order to start.
  2. If you need to set any custom configurations before the HCL logic starts, you can create a preConfigure.sh script and save it to the /SETUP/bin/ directory of the Docker image. For example, if you want to retrieve key-value pairs from a remote configuration management center other than Vault, then you need to customize the /SETUP/bin/preConfigure.sh script to connect to your configuration management center.
  3. Determine how to pass Docker start up parameters.
    1. If you do not use Vault, you can specify CONFIGURE_MODE=EnvVariables. This triggers the /SETUP/bin/envVariablesConfigure.sh script and pulls parameters from the container environment variables.
    2. HCL Commerce Docker images are configured to support Vault as a configuration management center. If you set up your parameters in Vault, you can specify CONFIGURE_MODE=Vault. This triggers the /SETUP/bin/vaultConfigure.sh script that can pull parameters from your Vault as long as you provide the VAULT_TOKEN and VAULT_URL.
      • The script needs each Docker service host name to contain the <TENANT>/<ENVIRONMENT>/<ENVTYPE>/<TARGET_KEY> values, and environment-related configuration data must be organized as <TENANT>/<ENVIRONMENT>/<ENVTYPE>/<TARGET_KEY>. For more information about how to organize your data in Vault, see Environment data structure in Consul/Vault.
      • This method is designed to support multi-tenant environments on Docker orchestration platforms. It is best used in a CI/CD pipeline where you have the ability to resolve the TENANT, ENVIRONMENT, ENVTYPE, and STOREWEB_HOST parameters.
      • This method follows a fixed pattern to set each container's host name during container start up. For example, the Transaction server container host name is set as <TENANT><ENVIRONMENT><ENVTYPE>tsapp.<DOMAIN-NAME>
    3. If you want to quickly deploy an environment with minimal changes, you can omit the CONFIGURE_MODE parameter and specify values as container environment variables. This method only supports some parameters so customization is limited in this mode.

    Also, if you configured Vault as a certificate authority with a PKI back end, then you can also pass VAULT_CA=true. This triggers the /SETUP/bin/updateCerts.sh script to configure internal certification between Docker containers. For more information, see Managing certificates with Vault.

  4. Next, entrypoint triggers the /SETUP/bin/custConfiguration.sh script, which allow for another point of customization where you can customize any aspect of the Docker container start up logic.
    • If you are handling certificates locally and not using Vault, you can define your certificate information in a JSON file and save it to /SETUP/certs/custom. The /SETUP/bin/updateLocalCerts.sh script looks in the /SETUP/certs/custom directory and loads all JSON files. For more information, see Managing certificates manually.
    • If you want to customize any start up logic scripts, you can create a /SETUP/bin/custConfiguration.sh script to include your own logic. This is the last script to run during container start up. Any configurations that you specify in custConfiguration.sh supercede any configurations from previous scripts. For example if the /SETUP/bin/vaultConfigure.sh, /SETUP/bin/envVariablesConfigure.sh, or /SETUP/bin/updateLocalCerts.sh scripts do not meet your requirements, it is recommended that you use those scripts as a starting point. Follow the same skeleton and update or add any custom logic into the postConfiguration.sh script.
Tip: To add any of your custom files to the Docker image (preConfigure.sh, custConfiguration.sh, *.json), create a Dockerfile and define a COPY instruction to copy the file into the new target location of the Docker image. Then use the Dockerfile to build a custom Docker image.

Viewing help and license information

You can run the following commands without starting the container.
  • List basic usage information.
    docker run -it -e LICENSE=accept <Docker image> help 
  • Show license terms and agreements in English.
    docker run -it -e LICENSE=accept <Docker image> LicenseView
  • Show license terms and agreements in other languages.
    docker run -it -e LICENSE=accept -e lang=<cs|el|es|in|ja|lt|pt|sl|zh|de|en|fr|it|ko|pl|ru|tr|zh_TW> <Docker image> LicenseView
You can also read the /SETUP/bin/entrypoint.sh script to understand the start up logic.

Starting containers with various configuration options

Each HCL Commerce Docker container has its own mandatory parameters that you need to provide for the container to start. There are also optional parameters that you can specify to further customize your container. For more information, see the following topics.