Docker container start up logic for 9.0.0.0 and 9.0.0.1

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.

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

1 Starting containers

HCL provided Docker images have embedded default configurations so that you 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>

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, you 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. For more information, see Loading the HCL Commerce database schema.

The <encrypted_spiuser_pw> is the encrypted password for the user 'spiuser'. For more information, see Setting the spiuser password in your Docker images.

Here are the configuration values that are set by default.

By default, 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 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 you 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. 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
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 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 Building custom Docker images for use with an Oracle database.

Note: To learn how to start containers and deploy environments by using Docker Compose, see Deploying HCL Commerce Version 9.0.0.0 to 9.0.1.17 authoring and live environments with Docker Compose (for non-production usage).

2 Setting configuration parameters

By default, there is a /SETUP/bin/configure.sh script in each Docker container. Each script defines the HCL default configurations that are used to start that specific container. Use this default configuration logic as a reference if you want to set your 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 you need to 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 your customization needs, you 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 you define in this custConfiguration.sh file supersedes any other configurations that you 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)

You 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 your own values when you specify OVERRIDE_PRECONFIG=true?

By default, Vault and Consul are supported for storing sensitive key-value pairs for your Docker configurations. If you are using Vault, update Vault with your values. Then, you 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. For more information, see Environment data in 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>
```
- ```
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 you are starting the container in a command line interface, you 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>
```
- ```
docker run -it -e LICENSE=accept -e OVERRIDE_PRECONFIG=true <mandatory_parameters> <optional_parameters> <Docker_image>
```
If you want to implement a deployment pipeline, you 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 you can decide on your own configuration management tool to use. If you want 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, your 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><environment><envtype>tsapp.<domain-name>

3 Handling certificates

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

Internal certificates
By 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. You must enable the PKI feature. For a sample implementation, see Install Consul and Vault for configuration and certification management.
2. You must specify VAULT_CA=true as a Docker environment variable.
3. You 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. For more information, see Environment data in Vault.
If you do not want to use the default internal certification logic, you can define your own logic in the custConfiguration.sh script.
External certificates for third-party integrations
There 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. For more information, see the sample implementation,
- Load the third-party certificates locally. You can put certificate related information in a JSON file under SETUP/certs/custom in each target Docker container. You 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 Managing certificates manually.
  Alternatively, you can customize the Docker start up flow (with custConfiguration.sh) to include your own certification update logic.

4 Additional Configuration

As you customize HCL Commerce, you 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 you can create this script to execute post-configuration logic. Use this script to either override the Docker container start up logic, or add your own configurations as needed.
You 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.