Docker container startup logic for Commerce+

Startup sequence

1. When you deploy a container from an HCL-provided image, the entrypoint.sh script is executed. This script determines the configurations to use while starting up the container.

   License Acceptance Check

   The script first checks for license acceptance. All containers require LICENSE=accept to be passed in order to start.

   Custom Pre-Configuration

   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 Commerce Lab other than Vault, customize the /SETUP/bin/preConfigure.sh script to connect to your configuration Commerce Lab.

2. Next, the script determines how to pass Docker startup parameters based on the CONFIGURE_MODE environment variable. This variable takes one of two values or can be omitted (see Startup with CONFIGURE_MODE=EnvVariables and Startup with CONFIGURE_MODE=Vault for detailed configuration instructions).

   Omit CONFIGURE_MODE

   Specify the default configuration by omitting the CONFIGURE_MODE parameter. If you want to quickly deploy an environment with minimal changes, you can specify your values as container environment variables. This method only supports some parameters, so customization is limited.

   CONFIGURE_MODE=EnvVariables

   This is the Environment Variables configuration. Specify this configuration if you do not intend to use Vault. It triggers the /SETUP/bin/envVariablesConfigure.sh script, which pulls parameters from the container environment variables.

   For detailed instructions, see Startup with CONFIGURE_MODE=EnvVariables.

   CONFIGURE_MODE=Vault

   Use this value if you set up your parameters in Vault. It triggers the /SETUP/bin/vaultConfigure.sh script, which pulls parameters from your Vault as long as you provide VAULT_TOKEN and VAULT_URL information.

   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 example, for a Transaction server container, the host name might be set as <TENANT><ENVIRONMENT><ENVTYPE>tsapp.<DOMAIN-NAME>.

   For detailed instructions, see Startup with CONFIGURE_MODE=Vault

3. After the system has determined how to pass Docker environment variables, it will perform certificate configuration if you have configured Vault as a certificate authority. Set VAULT_CA=true to trigger the /SETUP/bin/updateCerts.sh script if Vault is configured as a certificate authority with a PKI backend.
4. Next, entrypoint.sh triggers the /SETUP/bin/custConfiguration.sh script, which provides two further customizations options for Docker container startup:

   Local Certificate Handling

   If you are handling certificates locally and not using Vault, define your certificate information in a JSON file and save it to /SETUP/certs/custom. custConfiguration.sh invokes the /SETUP/bin/updateLocalCerts.sh script, which looks in the /SETUP/certs/custom directory and loads all JSON files there.

   Custom Startup Logic

   If you want to customize any startup logic scripts, create a /SETUP/bin/custConfiguration.sh script to include your own logic. This is the last script to run during container startup. Any configurations specified in custConfiguration.sh supersede any configurations from previous scripts.

5. To add any of your custom files to the Docker image (for example, preConfigure.sh, custConfiguration.sh, or *.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.
   1. Create a Dockerfile. Define a COPY instruction to copy custom files into the new target location of the Docker image. An example Dockerfile could be:

      FROM hcl/commerce:latest
      COPY preConfigure.sh /SETUP/bin/preConfigure.sh
      COPY custConfiguration.sh /SETUP/bin/custConfiguration.sh
      COPY custom-certs.json /SETUP/certs/custom/custom-certs.json

   2. Build the Custom Docker Image. Use the Dockerfile to build the custom Docker image.

Viewing Help and License Information

docker run -it -e LICENSE=accept Docker image help
docker run -it -e LICENSE=accept Docker image LicenseView
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

Starting Containers with Various Configuration Options

HCL Commerce+ Default Configurations

HCL-provided Docker images have embedded default configurations for quick deployment. If you do not use the default host names or database information, ensure that you pass in the necessary parameters during container startup.

Each container is configured with a specific host name and default certificate. For example: