Docker container start up logic for 9.0.0.0 and 9.0.0.1

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.

Default configurations 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 ENTRYPOINT calls the /SETUP/bin/configure.sh script. This script defines the IBM default configurations used to start the Docker containers. Each container has its own configure.sh script.

1 Starting containers

IBM provided Docker images have embedded default configurations so that we can quickly deploy a runtime environment without making any changes to the Docker image. Here are examples of how to start containers with all default settings by using native Docker commands.

• 

  • Transaction server Docker container:

    docker run -it -e LICENSE=accept -e SPIUSER_PWD=<encrypted_spiuser_pw> -e MERCHANTKEY_ENCRYPT=<encrypted_merchant_key> <txn_Docker_image>

  • Any other container:

    docker run -it -e LICENSE=accept -e SPIUSER_PWD=<encrypted_spiuser_pw> <Docker_image>

• (v9.0.0.0)

  • Transaction server Docker container:

    docker run -it -e LICENSE=accept -e MERCHANTKEY_ENCRYPT=<encrypted_merchant_key> <txn_Docker_image>

  • Any other container:

    docker run -it -e LICENSE=accept <Docker_image>

To read about the license terms and agreements, we can run

docker run -it -e LICENSE=accept -e lang=<lang_alias> Docker_image LicenseView

Where <lang_alias> is the language to read. Valid values are cs/de/el/en/es/fr/in/it/ja/ko/lt/pl/pt/ru/sl/tr/zh_TW/zh.

The <encrypted_merchant_key> is the encrypted key that is created during database schema initialization. See Loading the WebSphere Commerce database schema.

The <encrypted_spiuser_pw> is the encrypted password for the user 'spiuser'. See Setting the spiuser password in our Docker images. Here are the configuration values that are set by default.

• By default, 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 the host names do not match, then the connection fails.

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

Note: To learn how to start containers and deploy environments by using Docker Compose, see
Deploy a WebSphere Commerce environment locally.

2 Setting configuration parameters

By default, there is a /SETUP/bin/configure.sh script in each Docker container. Each script defines the IBM default configurations used to start that specific container. Use this default configuration logic as a reference to set our own configurations. The script is designed to be able to fetch container start up parameters from Vault. The script needs each Docker service host name to contain the{tenant}{environment_name}{env_type} values, and environment-related configuration data must be organized as {tenant}/{environment_name}/{env_type}/{target_key}. There are two methods to overriding the default configuration:

2.1 Setting configuration parameters method 1 (create new scripts)

If you do not use Vault or set some specialty configurations (such as connections to a configuration management system other than Vault), then create a /SETUP/bin/preConfigure.sh or /SETUP/bin/custConfiguration.sh script. Copy contents from /SETUP/bin/configure.sh into the new scripts, modify based on your requirements, and rebuild the Docker image. With this customized Docker image, the start up logic automatically triggers the preConfigure.sh or custConfiguration.sh scripts if the files exist. The preConfigure.sh script runs before the custConfiguration.sh script. Depending on our customization needs, we can decide to use both or only one of the scripts.

Note: This method is best used in a local, single server, or simple authoring/production environment system that does not leverage Docker orchestration tools that you would use in a CI/CD pipeline scenario. Also, any environment configurations that we define in this custConfiguration.sh file supersedes any other configurations that we might make since this is the last script to run. If you use this method, you do not have to specify OVERRIDE_PRECONFIG=true when you start the container.

2.2 Setting configuration parameters method 2 (OVERRIDE_PRECONFIG=true)

We can add the container environment parameter 'OVERRIDE_PRECONFIG=true' when you start a container. This parameter causes the start up process to execute logic to override the default values (from configure.sh) with values that you provide. Now, how do you provide our own values when you specify OVERRIDE_PRECONFIG=true?

• By default, Vault and Consul are supported for storing sensitive key-value pairs for our Docker configurations. If we are using Vault, update Vault with your values. Then, we can pass in the VAULT_TOKEN and VAULT_URL as an environment variable and the key-value pairs are automatically retrieved from Vault. Ensure that your key-value pairs are defined in the proper data structure. See Environment data structure in Consul/Vault. Here is an example of specifying the VAULT_TOKEN and VAULT_URL through a docker run command:

  • 

    docker run -it -e LICENSE=accept -e SPIUSER_PWD=<encrypted_spiuser_pw> -e OVERRIDE_PRECONFIG=true -e VAULT_URL=http://<VaultURL>:<port>/<directory> -e VAULT_TOKEN=<Vault_token> -e <Mandatory_Parameters_For_Vault> Docker_image

  • (v9.0.0.0)

    docker run -it -e LICENSE=accept -e OVERRIDE_PRECONFIG=true -e VAULT_URL=http://<VaultURL>:<port>/<directory> -e VAULT_TOKEN=<Vault_token> -e <Mandatory_Parameters_For_Vault> Docker_image

  For <Mandatory_Parameters_For_Vault>, see Docker container start up configuration parameters.

• If you do not pass in VAULT_TOKEN or VAULT_URL, then scripts try to retrieve values from the container environment parameters. Or, if we are starting the container in a command line interface, we can pass in the values through the command. For example,

  • 

    docker run -it -e LICENSE=accept -e SPIUSER_PWD=<encrypted_spiuser_pw> -e OVERRIDE_PRECONFIG=true mandatory_parameters optional_parameters Docker_image

  • (v9.0.0.0)

    docker run -it -e LICENSE=accept -e OVERRIDE_PRECONFIG=true <mandatory_parameters> optional_parameters Docker_image

• To implement a deployment pipeline, we can configure the pipeline to pass in the mandatory values into the container start up as environment variables. With this method, you remove the dependency on Consul/Vault and we can decide on our own configuration management tool to use. To retrieve key-value pairs from a remote configuration center other than Vault, then you need to customize the /SETUP/bin/preconfiguration.sh script to retrieve from your configuration center.

There are mandatory and optional parameters that you need to provide to the containers. If you do not set these mandatory parameters, the container will not start. For more information about the configuration parameters, see Docker container start up configuration parameters.

Note:

• This OVERRIDE_PRECONFIG=true 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 TENANT, ENVIRONMENT, ENVTYPE, and STOREWEB_HOST parameters. These are all mandatory parameters when OVERRIDE_PRECONFIG=true.

• This method requires that the multi-tenant environment and environment configuration data are organized specifically with a parent/child/grandchild directory structure as TENANT / ENVIRONMENT / ENVTYPE.

• 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>environmentenvtypetsapp.domain-name

3 Handling certificates

There are two types of certificates that are supported by the IBM provided Docker images; internal certificates between each running container and external certificates for third-party integrations.

• Internal certificatesBy default, Docker images are configured to be able to leverage the PKI feature in Vault to issue internal certificates to each Docker container. To use the predefined internal certification logic in the SETUP/bin/updateCerts.sh script to import certificates from Vault:

  1. We must enable the PKI feature. For a sample implementation, see Install Consul and Vault for configuration and certification management.

  2. We must specify VAULT_CA=true as a Docker environment variable.

  3. We must also specify VAULT_URL, VAULT_TOKEN, TENANT, Environment, and ENVTYPE as Docker environment variables. These values are needed to tell the script where to find the certificates.

  4. Ensure that Vault is configured with the proper data structure. See Environment data structure in Consul/Vault.

  If you do not want to use the default internal certification logic, we can define our own logic in the custConfiguration.sh script.

• External certificates for third-party integrationsThere are different ways to load third-party certificates:

  • Import third-party certificates along with the internal certificates in Vault (VAULT_CA=true). In this approach, you need to populate the certificate related information into Vault in the proper data structure. After internal certificates are imported, scripts will, based on path on Vault, check if the current container is bound with any third-party certificates. If yes, the third-party certificates are downloaded from Vault and imported into the container. See the sample implementation,

  • Load the third-party certificates locally. We can put certificate related information in a JSON file under SETUP/certs/custom in each target Docker container. We can create a new Docker image with a Dockerfile, and in the Dockerfile, copy the JSON file into the /SETUP/certs/custom directory. The updateLocalCerts.sh can detect and load any certificates that exist in /SETUP/certs/custom. For more information about creating the JSON files, see Manage certificates manually.

    Alternatively, we can customize the Docker start up flow (with custConfiguration.sh) to include our own certification update logic.

4 Additional Configuration

As you customize WebSphere Commerce, we might realize that you need to implement additional custom logic. The Docker images contain a postConfiguration.sh script that calls two actions:

• updateLocalCerts.sh. This script loads any local certificates that are in the SETUP/certs/custom directory.

• custConfiguration.sh does not exist by default but we can create this script to execute post-configuration logic. Use this script to either override the Docker container start up logic, or add our own configurations as needed.

  We can create a Dockerfile to build a new image and use the COPY instruction to copy the custConfiguration.sh script into the new Docker image into the /SETUP/bin directory.

• (v9.0.0.0) (v9.0.0.1) Docker container start up configuration parameters
  Whenever you specify OVERRIDE_PRECONFIG=true or VAULT_CA=true, there are mandatory parameters that you need to specify, otherwise the container will not start. The following tables summarize the list of mandatory and optional parameters for each container.

Related reference
WebSphere Commerce runtime environment overview
Docker container start up configuration parameters

Related information:

Implement a continuous deployment pipeline for WebSphere Commerce Version 9