Start transaction server Docker container

  1. View help and license information
  2. Start container with default configurations (do not specify CONFIGURE_MODE parameter)
  3. Start containers by retrieving parameters from Vault (CONFIGURE_MODE=Vault)
  4. Start containers by retrieving parameters from container environment variables (CONFIGURE_MODE=EnvVariables)
  5. (Additional optional configuration) Using Vault as a certificate authority


View help and license information

Read /SETUP/bin/entrypoint.sh to see start up logic. Parameters passed in as environment variables always have the highest priority.


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

Use this mode...

Default configuration mode is ideal for using Docker Compose. We can leverage the service name or network alias to ensure that the service names are the same as the default host names. We can specify the mandatory and optional parameters as environment: parameters in the Compose file. For examples on how to start WebSphere Commerce by using Docker Compose,

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

When starting with the default configurations, the Transaction server Docker container 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. To define our own certification logic or use different container host names, use the CONFIGURE_MODE parameter instead.

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

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. See Loading the WebSphere Commerce database schema.
SPIUSER_NAME Your SPIUSER name. Default is spiuser.
SPIUSER_PWD The encrypted password for the 'spiuser'. See
Setting the spiuser password in our Docker images

Optional parameters.

Parameter name Value
DBHOST
DBNAME
DBUSER
DBPASS
DBPORT 1
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.

1 Note: If you need to point to a different database, you need to specify all these parameters.


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

We can use 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. 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:

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 we 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, we can configure your domains to redirect to STOREWEB_HOST to ensure that preview works for all stores.

These are optional parameters. We can pass these parameters as container environment variables, or we can store them in Vault. If we 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. Default:

    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. We 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. We 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. We 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. We 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. We 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. We 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. See Loading the WebSphere Commerce database schema.
SPIUSER_NAME Your SPIUSER name. Default is spiuser.
SPIUSER_PWD The encrypted password for the 'spiuser'. See
Setting the spiuser password in our Docker images
LOCALSTOREWEB The web server host name of a local store if you migrated from WebSphere Commerce 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.
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
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 to configure the container to catch validation.
Works with KAFKA_SERVERS, to configure the container to catch validation.
SESSION_KEY_ENCRYPT Encrypted session key.


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

If you do not use Vault, we can retrieve parameters from container environment variables. 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.

If you use this method, and do not use the default host names, ensure the custom host name matches 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. We 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. See Loading the WebSphere Commerce database schema.
SPIUSER_NAME Your SPIUSER name. Default is spiuser.
SPIUSER_PWD The encrypted password for the 'spiuser'. See
Setting the spiuser password in our Docker images
STOREWEB_HOST The external store hostname that can be used to access the store by a browser. If we 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, we 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. Default:

    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. We 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 WebSphere Commerce 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 to configure the container to catch validation.
Works with KAFKA_SERVERS, 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.


Use Vault as a certificate authority (VAULT_CA=true)

If you have Vault configured as a certificate authority (CA), we can use VAULT_CA=true, which triggers...

...in the Docker image to handle internal certification between the containers.

VAULT_CA=true is an independent configuration that we can use with any of the three modes (CONFIGURE_MODE=Vault, CONFIGURE_MODE=EnvVariables, or no configuration mode). If we are using CONFIGURE_MODE=Vault|EnvVariables, ensure that you also specify the mandatory parameters for our 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.


Starting a container with VAULT_CA=true but without CONTAINER_HOSTNAME

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

This method is ideal in a Docker orchestration platform such as Kubernetes or DC/OS where we 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,


(v9.0.0.2)

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

Starting with WebSphere Commerce Version 9.0.0.2, we can start the container with VAULT_CA=true and CONTAINER_HOSTNAME=<customHostName>. Use this method on our own custom environment where you do not have <TENANT><ENVIRONMENT><ENVTYPE>. For example, if we are using a local environment and we 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