Setting the spiuser password in your Docker images

An administrator needs to choose a password for a default SPI user that is named spiuser, and then set the spiuser password in the HCL Commerce Docker containers.

This password is used for inter-component server API invocation only.

This password is stored for the Store server, Search server and Customization server within the WebSphere Application Server V8.5.5 Liberty userregistry.xml configuration file. In the Transaction server, the spiuser user is configured in the database.

The password must be the same on all servers, and each Docker image must be configured with the correct spiuser user password. If the passwords do not match, or if a container is left unconfigured, then the component servers cannot make the required API calls to function together.

The following API call flows use the spiuser credentials:
  • The Store server calls the Search server and Transaction server.
  • The Customization server calls the Transaction server.
  • The Transaction server calls the Customization server.
  • The Search server calls the Transaction server, Customization server, and other Search servers.
  • Ensure that you use a secure password.


  1. Log on to the dedicated server that is hosting the Utility server Docker container.
    If a Utility server Docker container is not deployed, see Preparing a Docker host server to launch Utility server Docker container.
  2. Enter the Utility server Docker container.
    For example,
    docker exec -it utility_container_name bash
  3. Go to the /opt/WebSphere/CommerceServer90/bin directory.
  4. Run the following command to encrypt the spiuser password.
    ./ plain_text_spiuser_password
  5. Copy and save the plain_text_spiuser_password within a text file.

    You require the plain text password to deploy the HCL Commerce containers.

  6. Generate the merchantKey encrypted password, and store it in the database.
    1. Obtain the salt value for the spiuser password.
      1. Open a database command line prompt, and run the following against your database to obtain the salt value.
        select salt from userreg where logonid='spiuser';
      2. If the result that is returned is NULL, you must set a salt value for the spiuser password.
        update userreg set salt='salt' where logonid='spiuser';
        Where salt is 12 random alphanumeric characters from the following set:

        For example, m83u229zjsrv.

    2. Encrypt the salted password with the merchantKey.
      In a separate command prompt, run the following HCL Commerce command utility located in the /opt/WebSphere/CommerceServer90/bin directory.
      ./ plain_text_spiuser_password salt unencrypted_merchantKey_value
      Note: The wcs_password utility can also be used with the -k parameter to encrypt the salted password without needing to provide the unencrypted merchant key.

      This parameter is mandatory when the merchant key has a version specified, for example, in a separate custom key configuration file, CustomKeys.xml.

      For more information, on the wcs_password utility, see Generate HCL Commerce encrypted password (wcs_password).

      A merchantKey encrypted version of the salted password is output in ASCII and hexadecimal formats.
    3. Store the encrypted password in the database.
      In a database command line prompt, update the encrypted password based on the database solution that you are using.
      • DB2
        update userreg set logonpassword=x'encrypted_hexadecimal_output' where logonid = 'spiuser';
        Note: The x'encrypted_hex_output' is required to store the value in hexadecimal format.
      • Oracle
        update userreg set logonpassword='encrypted_hexadecimal_output' where logonid = 'spiuser';
  7. Exit the Docker container.
  8. Share the plain text spiuser password with your development team.
    Note: Developers need to use the plain text password when they load the HCL Commerce schema to the database. Particularly, developers need to provide the spiuser password when Loading the HCL Commerce database schema.


Your HCL Commerce Docker containers are now configured and can now communicate via API calls.

What to do next

Set the spiuser user name (optional) and the spiuser user password (mandatory) during deployment for the HCL Commerce services that require them. These values can be passed as environment variables, or defined in Vault. For more information on the deployment start-up process, see Docker container start up logic for HCL Commerce Version or later.