Starting the

Learn how to start the . There are mandatory and optional parameters that you can specify depending on how you want to start your container.

There are three main configuration modes that you can use to start containers.

Starting container with default configurations (do not specify CONFIGURE_MODE parameter)
Starting containers by retrieving parameters from Vault (CONFIGURE_MODE=Vault)
Starting containers by retrieving parameters from container environment variables (CONFIGURE_MODE=EnvVariables)
(Additional optional configuration) Using Vault as a certificate authority

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

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 ts-app help 
```
Show license terms and agreements in English.
```
docker run -it -e LICENSE=accept ts-app 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 ts-app LicenseView

Starting container with default configurations (do not specify CONFIGURE_MODE parameter)

Use this mode in the following scenarios.

You only want to view files inside the container and do not need the container to connect and communicate with other containers.
Your entire Docker environment (database and other containers) uses all IBM default values for passwords and container host names. If you do not use the default host names and passwords, do not use this method. Your container will not function properly.
You are deploying locally as an individual test environment.

Note: This configuration mode is ideal for using Docker Compose. You can leverage the service name or network alias to ensure that the service names are the same as the default host names. You can specify the mandatory and optional parameters as environment: parameters in the Compose file. For examples on how to start 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).

To start the container with default configurations to view files inside the container, use:

docker run -it -e LICENSE=accept ts-app

When you start by using the default configurations, the host name is app.

To start a functional container without specifying CONFIGURE_MODE, ensure that all Docker containers in the environment use the IBM default container host names and default certification logic. If you want to define your own certification logic or use different container host names, use the CONFIGURE_MODE parameter instead.

The default host names for all containers.


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 you are running a Db2 Docker container. If you are not using a Db2 Docker with the host name as db, then you cannot start the container by using the default configurations.	db

The default SubjectAlternativeName in container certification.
```
[DNSName: *, DNSName: db, DNSName: search, DNSName: store, DNSName: xc, DNSName: app]
```

You are using the default datasource credentials.


Database parameters	Value
Database type (dbType)	db2
JNDI	jdbc/WCDataSource
Database instance name (dbName)	mall
Database user (dbUser)	wcs
Database user password (dbUserPass)	wcs1
Database host (dbHost)	db
Database port (dbPort)	50000

If your environment satisfies the default conditions, you can run the following command. If you are using Docker Compose, ensure that you specify these parameters as environment: variables in your compose file.

docker run -it -e LICENSE=accept  \
    -e Parameter1=Value1
    -e Parameter2=Value2
    ...
    ts-app

Mandatory parameters


Parameter name	Value
MERCHANTKEY_ENCRYPT	The encrypted merchant key that was created when you or an administrator loaded the WebSphere Commerce database schema. For more information, see Loading the HCL Commerce database schema.
SPIUSER_NAME	Your SPIUSER name. The default value is spiuser.
SPIUSER_PWD	The encrypted password for the 'spiuser'. For more information, see Setting the spiuser password in your Docker images

Optional parameters


Parameter name	Value
DBHOST DBNAME DBUSER DBPASS DBPORT Note: If you need to point to a different database, you need to specify all these parameters.	The database hostname.
	The name of the database.
	The database user name.
	The database user password.
	The database port.
DB_SSLENABLE	Determines whether to enable SSL protocol for connections to the database. Valid values are true or false. Default value is false.
DB_XA	Specify if the XA function has been enabled for database. Default value is false.
adminPassword	The password for user configadmin, which is used to access the WebSphere Application Server Administrative Console.
SCHEDULER_ID	Specify SchedulerHostName in TWAS JVM for Transaction server container for scheduler. The default value is the Docker hostname.
SCHEDULER_CLONEID	Specify SchedulerCloneId in TWAS JVM for Transaction server container for scheduler. The default value is the Docker hostname.

Starting containers by retrieving parameters from Vault (CONFIGURE_MODE=Vault)

You can use Vault as a configuration management center and set your parameters in Vault. This method is best used in a multiple tenant environment by using an orchestration platform such as Kubernetes. All service names are automatically generated and configured following the unique naming pattern:${TENANT}${ENVIRONMENT}${ENVTYPE}<component>.${DOMAIN_NAME} For example, for ts-app with TENANT=demo, ENVIRONMENT=qa, ENVTYPE=auth, the container's service unique naming pattern will be demoqaauthts-app.default.svc.cluster.local

Note:

CONFIGURE_MODE=Vault is not recommended and is not supported if you are deploying on a local machine since the unique naming pattern cannot be identified on your local system.
For information about how to organize environment data on Vault, see Environment data in Vault.
For information about how to set up Vault, see .

Mandatory parameters

These are the mandatory parameters that you need to specify to configure the container to retrieve more parameters from Vault.


Parameter name (key)	Value
TENANT	The name of the group that contains your set of environments. For example, `MyCompany`.
ENVIRONMENT	The name of the environment. For example, `Non-production`.
ENVTYPE	Then type of environment. For example, `auth`.
VAULT_TOKEN	The Vault token to use to connect to Vault and request certification from Vault PKI.
VAULT_URL	The HTTP API endpoint to connect to Vault and request certification from Vault PKI. For example, http://Vault_IP:8200/v1.
STOREWEB_HOST	A unique hostname for use with Management Center Store preview. If you are using DC/OS, this is the internal DNS in DC/OS. For example, store-wytryqaauth.cn.ibm.com. Note: If you have multiple stores running on multiple domains, you can configure your domains to redirect to STOREWEB_HOST to ensure that preview works for all stores.

Optional parameters

These are optional parameters. You can pass these parameters as container environment variables, or you can store them in Vault. If you store the key-value pairs in Vault, the /SETUP/bin/vaultConfigure.sh script retrieves the values from Vault. All parameters that you specify as container environment variables take precedence over the values that are stored in Vault.


Parameter name (key)	Value
DOMAIN_NAME	The internal service domain name. The default value is : default.svc.cluster.local. If the deployed environment is on a special namespace on Kubernetes, the domain name should be `.svc.cluster.local`.
DBHOST DBNAME DBUSER DBPASS DBPORT Note: If you need to point to a different database, you need to specify all these parameters. You can also specify datasource credentials through the start up command if you do not want to retrieve the datasource values from Vault.	The database hostname.
	The name of the database.
	The database user name.
	The database user password.
	The database port.
DB_SSLENABLE	Determines whether to enable SSL protocol for connections to the database. Valid values are true or false. Default value is false. You can also specify datasource credentials through the start up command if you do not want to retrieve the datasource values from Vault.
DB_XA	Specify if the XA function has been enabled for database. Default value is false. You can also specify datasource credentials through the start up command if you do not want to retrieve the datasource values from Vault.
DBHOST_LIVE DBNAME_LIVE DBPASS_LIVE DBPORT_LIVE DBUSER_LIVE Note: If you need to point to a different live database, you need to specify all these parameters. You can also specify datasource credentials through the start up command if you do not want to retrieve the datasource values from Vault.	The database hostname in the live environment.
	The name of the database in the live environment.
	The database user password in the live environment.
	The database port in the live environment.
	The database user name in the live environment.
DB_SSLENABLE_LIVE	Determines whether to enable SSL protocol for connections to the live database. Valid values are true or false. Default value is false. You can also specify datasource credentials through the start up command if you do not want to retrieve the datasource values from Vault.
DB_XA_LIVE	Specify if the XA function has been enabled for the live database. Default value is false. You can also specify datasource credentials through the start up command if you do not want to retrieve the datasource values from Vault.
MERCHANTKEY_ENCRYPT	The encrypted merchant key that was created when you or an administrator loaded the WebSphere Commerce database schema. For more information, see Loading the HCL Commerce database schema.
SPIUSER_NAME	Your SPIUSER name. The default value is spiuser.
SPIUSER_PWD	The encrypted password for the 'spiuser'. For more information, see Setting the spiuser password in your Docker images
LOCALSTOREWEB	The web server host name of a local store if you migrated from Version 7 or Version 8.
HEALTH_CENTER_ENABLED	Determines whether Health Center is enabled (true/false). Default value is false.
adminPassword	The password for user configadmin, which is used to access the WebSphere Application Server Administrative Console.
TRACE_SPEC	Sets trace specifications. For more information about trace, see Trace components
BLUE_ID_SERVER BLUE_ID_PROVIDERHOST OIDC_CLIENT_ID OIDC_CLIENT_SECRET Note: These parameters must be provided together to fully configure single-sign on.	The IBMid server. For example, idaas.iam.ibm.com
	The provider host for single sign-on.
	No Default Value, works with OIDC_CLIENT_ID to enable IBMid feature
	No Default Value, works with OIDC_CLIENT_SECRET to enable IBMid feature for single sign-on.
KAFKA_SERVERS ZOOKEEPER_SERVERS Note: These parameters must be provided together.	The Kafka server. Works with ZOOKEEPER_SERVERS if you want to configure the container to catch validation.
	Works with KAFKA_SERVERS, if you want to configure the container to catch validation.
SESSION_KEY_ENCRYPT	The encrypted session key.

Starting containers by retrieving parameters from container environment variables (CONFIGURE_MODE=EnvVariables)

If you do not use Vault, you can retrieve parameters from container environment variables. For example, if you are using docker run, you can pass all parameters through command line, or if you are setting up a pipeline, you can set your pipeline to provide the parameters.

docker run -it -e LICENSE=accept  \
    -e CONFIGURE_MODE=EnvVariables    
    -e <Parameter1>=<Value1>
    -e <Parameter2>=<Value2>
    <Transaction Docker image>

Note: If you use this method and do not use the default host names, ensure that your custom host name matches the SubjectAlternativeNames in related certifications in other containers.

Mandatory parameters.


Parameter name	Value
DBHOST DBNAME DBUSER DBPASS DBPORT DBAUSER DBAPASSENCRYPT DBPASSENCRYPT Note: If you need to point to a different database, you need to specify all these parameters. You can also specify datasource credentials through the start up command if you do not want to retrieve the datasource values from Vault.	The database hostname.
	The name of the database.
	The database user name.
	The database user password.
	The database port.
	The user name of the database administrator.
	The encrypted password of the database administrator.
	The encrypted password of the database user.
MERCHANTKEY_ENCRYPT	The encrypted merchant key that was created when you or an administrator loaded the WebSphere Commerce database schema. For more information, see Loading the HCL Commerce database schema.
SPIUSER_NAME	Your SPIUSER name. The default value is spiuser.
SPIUSER_PWD	The encrypted password for the 'spiuser'. For more information, see Setting the spiuser password in your Docker images
STOREWEB_HOST	The external store hostname that can be used to access the store by a browser. If you are using DC/OS or Kubernetes, this is the exposed hostname on the load balancer, such as store.demoqaauth.cn.ibm.com. Note: If you have multiple stores running on multiple domains, you can configure your domains to redirect to STOREWEB_HOST to ensure that Management Center store preview works for all stores. The Transaction server will identify the different stores through the ID in the store URL.
SEARCH_HOST	Search server hostname. Default port is 3738.
STORE_HOST	Store server hostname. Default port is 8443.
XC_HOST	Customization server hostname. Default port is 9443.

Optional parameters.


Parameter name	Value
DOMAIN_NAME	The internal service domain name. The default value is : default.svc.cluster.local. If the deployed environment is on a special namespace on Kubernetes, the domain name should be `.svc.cluster.local`.
DBHOST_LIVE DBNAME_LIVE DBPASS_LIVE DBPORT_LIVE DBUSER_LIVE Note: If you need to point to a different live database, you need to specify all these parameters. You can also specify datasource credentials through the start up command if you do not want to retrieve the datasource values from Vault.	The database hostname in the live environment.
	The name of the database in the live environment.
	The database user password in the live environment.
	The database port in the live environment.
	The database user name in the live environment.
LOCALSTOREWEB	The web server host name of a local store if you migrated from Version 7 or Version 8.
adminPassword	The password for user configadmin, which is used to access the WebSphere Application Server Administrative Console.
TRACE_SPEC	Sets trace specifications. For more information about trace, see Trace components
BLUE_ID_SERVER BLUE_ID_PROVIDERHOST OIDC_CLIENT_ID OIDC_CLIENT_SECRET Note: These parameters must be provided together to fully configure single-sign on.	The IBMid server. For example, idaas.iam.ibm.com
	The provider host for single sign-on.
	No Default Value, works with OIDC_CLIENT_ID to enable IBMid feature
	No Default Value, works with OIDC_CLIENT_SECRET to enable IBMid feature for single sign-on.
KAFKA_SERVERS ZOOKEEPER_SERVERS Note: These parameters must be provided together.	The Kafka server. Works with ZOOKEEPER_SERVERS if you want to configure the container to catch validation.
	Works with KAFKA_SERVERS, if you want to configure the container to catch validation.
HEALTH_CENTER_ENABLED	Determines whether Health Center is enabled (true/false). Default value is false.
SESSION_KEY_ENCRYPT	Encrypted session key.
SEARCH_PORT	Self-defined search server port. Default value is 3738.
STORE_PORT	Self-defined store server port. Default value is 8443.
STOREWEB_PORT	Self-defined store web server port. Default value is 443.
XC_PORT	Self-defined Customization server port. Default value is 9443.

For example, to start with mandatory parameters, run the following command.

docker run -it -e LICENSE=accept  \
    -e CONFIGURE_MODE=EnvVariables
    -e MERCHANTKEY_ENCRYPT=<encrypted merchantkey that you encrypted with wcs_encrypt.sh> \
    -e SPIUSER_NAME=<your spiuser-name> \
    -e SPIUSER_PWD=<your spiuser password that you encrypted with wcs_encrypt.sh> \
    -e DBHOST=<db hostname> \
    -e DBNAME=<db instance name> \
    -e DBPASS=<db user password> \
    -e DBPORT=<db port> \
    -e DBUSER=<db user> \
    -e STOREWEB_HOST=<Store server hostname for Store preview that can be accessed from your browser. Default port is 443> \
    -e STORE_HOST=<store server hostname, default port is 8443> \
    -e SEARCH_HOST=<search server hostname, default port is 3738>\
    -e XC_HOST=<search server hostname, default port is 3738>\
    <Transaction Docker image>

Using Vault as a certificate authority (VAULT_CA=true)

If you have Vault configured as a certificate authority (CA), you can use VAULT_CA=true, which triggers /SETUP/bin/updateCerts.sh in the Docker image to handle internal certification between your containers. For information about configuring Vault as a CA, see Managing certificates with Vault.

VAULT_CA=true is an independent configuration that you can use with any of the three modes (CONFIGURE_MODE=Vault, CONFIGURE_MODE=EnvVariables, or no configuration mode). If you are using CONFIGURE_MODE=Vault|EnvVariables, ensure that you also specify the mandatory parameters for your mode. For example, if you enable CONFIGURE_MODE=Vault and VAULT_CA=true, then you need to specify TENANT, ENVIRONMENT, and ENVTYPE because it is needed for CONFIGURE_MODE=Vault. When you read the container parameters and notice that the same variables are used in different configuration modes (such as VAULT_TOKEN), you just need to define it once as a container environment variable. The different configuration modes will share the same variables that you provide.

The parameter VAULT_CA=true also has it's own two configuration modes.

Without CONTAINER_HOSTNAME
With CONTAINER_HOSTNAME=<customHostName>

Starting a container with VAULT_CA=true but without CONTAINER_HOSTNAME

Use this method in an environment where your container variables are grouped in the form <TENANT><ENVIRONMENT><ENVTYPE><TARGETKEY>. For example, if you use VAULT to store your parameters and you are using CONFIGURE_MODE=Vault.

This method is ideal in a Docker orchestration platform such as Kubernetes or DC/OS where you can resolve <TENANT><ENVIRONMENT><ENVTYPE>. When VAULT_CA=true, the start up logic /SETUP/bin/updateCerts.sh applies the internal certification based on the unique naming pattern <TENANT><ENVIRONMENT><ENVTYPE><DOCKER_CONTAINER>.<DOMAIN_NAME> as the common_name and SubjectAlternativeName. With this mode, the host name is fixed. If you do not provide a DOMAIN_NAME, the default is default.svc.cluster.local.

For example, to start a container with the DOMAIN_NAME as txn,

docker run -it -e LICENSE=accept  \
    -e VAULT_TOKEN=<vault_token > \
    -e VAULT_URL=<vault_url. For example, http://IP:Port/v1> \
    -e VAULT_CA=true \
    -e TENANT=<tenantValue> \
    -e ENVIRONMENT=<environmentValue. For example, non-prod> \
    -e ENVTYPE=<envtypeValue. For example, auth> \
    -e DOMAIN_NAME=<The container's hostname, which will be used to apply certification. For example, txn> \
    -e <Parameter1>=<Value1>
    -e <Parameter2>=<Value2>
    .... 
    <Docker_Image>

Starting a container with VAULT_CA=true and CONTAINER_HOSTNAME=<customHostName>

Starting with HCL Commerce Version 9.0.0.2, you can start the container with VAULT_CA=true and CONTAINER_HOSTNAME=<customHostName>. Use this method on your own custom environment where you do not have <TENANT><ENVIRONMENT><ENVTYPE>. For example, if you are using a local environment and you are not using CONFIGURE_MODE=Vault, then you will want to specify CONTAINER_HOSTNAME.

When CONTAINER_HOSTNAME is passed, the start up logic /SETUP/bin/updateCerts.sh applies the internal certification based on the CONTAINER_HOSTNAME as the certificate's common_name and SubjectAlternativeName.

For example, to start a container with host name mycontainerhostname

docker run -it -e LICENSE=accept  \
    -e VAULT_TOKEN=<vault_token > \
    -e VAULT_URL=<vault_url. For example, http://IP:Port/v1> \
    -e VAULT_CA=true \  
    -e CONTAINER_HOSTNAME=mycontainerhostname   
    -e <Parameter1>=<Value1>
    -e <Parameter2>=<Value2>
    ....
    <Docker_Image>