(v9.0.0.2)

Docker container start up logic for 9.0.0.2 or later

When we deploy a container from an IBM 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 we can customize the configurations.

By understanding the start up process of these Docker containers, we can learn how to customize the configurations to meet your needs and integrate with the 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

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

WebSphere Commerce default configurations

IBM provided Docker images have embedded default configurations so that we 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 WebSphere 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 used in a request is the same as the SubjectAlternativeName in the certificate on the target container. If we 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-db Note: This assumes that we are running a Db2 Docker container.	db

  If you do not use the default host names from the table, then you need to update the SubjectAlternativeName in your certificates. See Manage 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
  JNDI	For the Transaction server: jdbc/WCDataSource For the Search server: jdbc/wcdb
  Database instance name (dbName)	mall
  Database user (dbUser)	wcs
  Database user password (dbUserPass)	wcs1
  Database host (dbHost)	db
  Database port (dbPort)	50000

  If we 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
  Configure 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. IBM 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.

1. entrypoint.sh first checks for license acceptance. All containers require LICENSE=accept to be passed in order to start.

2. If set any custom configurations before the IBM logic starts, we can create a preConfigure.sh script and save it to the /SETUP/bin/ directory of the Docker image. For example, 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, we can specify CONFIGURE_MODE=EnvVariables. This triggers the /SETUP/bin/envVariablesConfigure.sh script and pulls parameters from the container environment variables.

   2. WebSphere Commerce Docker images are configured to support Vault as a configuration management center. If you set up your parameters in Vault, we can specify CONFIGURE_MODE=Vault. This triggers the /SETUP/bin/vaultConfigure.sh script that can pull parameters from the 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. To quickly deploy an environment with minimal changes, we 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 we can also pass VAULT_CA=true. This triggers the /SETUP/bin/updateCerts.sh script to configure internal certification between Docker containers. See Manage certificates with Vault.

4. Next, entrypoint triggers the /SETUP/bin/postConfigure.sh script, which allow for another point of customization where we can customize any aspect of the Docker container start up logic.

   • If we are handling certificates locally and not using Vault, we 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 Manage certificates manually.

   • To customize any start up logic scripts, we can create a /SETUP/bin/postConfiguration.sh script to include our own logic. This is the last script to run during container start up. Any configurations that you specify in postConfiguration.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 we 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 our custom files to the Docker image (preConfigure.sh, postConfiguration.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

We 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

We can also read the /SETUP/bin/entrypoint.sh script to understand the start up logic.

Start containers with varies configuration options

Each WebSphere Commerce Docker container has its own mandatory parameters that you need to provide for the container to start. There are also optional parameters that we can specify to further customize the container. See the following topics.

• Start container with default configurations
  Learn how to start the containers with the default configurations. That is without specifying the CONFIGURE_MODE parameter. There are mandatory and optional parameters that we can specify depending on how we want to start the container.

• Starting containers by retrieving parameters from Vault
  We can use Vault (CONFIGURE_MODE=Vault) as a configuration management center and set your parameters in Vault. This method is best used in a multiple tenant environment using an orchestration platform such as Kubernetes.

• Starting containers by retrieving parameters from container environment variables
  If you do not use Vault, we can retrieve parameters from container environment variables (CONFIGURE_MODE=EnvVariables). For example, if we are using docker run, we can pass all parameters through command line, or if we are setting up a pipeline, we can set the pipeline to provide the parameters.

• Optional: Using Vault as a certificate authority
  We can use vault as a certificate authority by specifying VAULT_CA=true. This is an optional configuration and can be used with any of the configuration mode supported to handle internal certification between the containers.