Deploying HCL Commerce Version 9.1.6.0 or greater with Docker Compose (for non-production usage)

You can deploy HCL Commerce Version 9.1 simply using Docker Compose. Generally, you deploy an authoring environment and a live environment to work together. In this standard HCL Commerce configuration, you update and modify your store in the authoring environment, and then propagate the changes to the live environment.

Beginning with HCL Commerce 9.1.12.0, the Docker Compose deployment can also be used to aid in the installation of HCL Commerce Developer.

Important:

This environment should not be used for a live production site as it misses some required production grade components and considerations, such as security hardening, deployment orchestration and load balancing for high availability support, ingress routing, and performance tuning capabilities. To operate HCL Commerce Version 9.1 in a live production environment, you must deploy it in a Kubernetes cluster and commit further time and resources to performance and security considerations.
With load balancing and ingress routing specifically, you can configure which services you want to expose externally, and restrict the remaining services within the cluster network. This configuration limits their access from and exposure to the wider Internet.
HCL Commerce Docker Compose deployments do not support the use of the root user. Beginning in HCL Commerce 9.1.14.0, application container images are built to be run as a non-root user by default. This change has the potential to break your custom deployment. Therefore, you must review this change and its potential impacts. For more information, see HCL Commerce container users and privileges.

The Docker-based deployment was simplified, and features additional automation in the 9.1.6.0 release.

Specific improvements include:

A simplified directory structure for mounted volumes.
- For the ease of import of essential files into your Docker images, without the need to create or recreate custom images;
- For persistence of HCL Commerce demo data, in the event that your containers are taken offline or restarted.
- Automated deployment of Docker images for use within an HCL Commerce development environment.
For more information on mounted volumes, see The Docker Compose deployment /volumes/ directory structure and contents.
Improved deployment automation. Simply update the required environment information and run a script to configure and deploy HCL Commerce and related applications. This eliminates the need to manual edit your deployment files, which can be error-prone.
For more information on deployment configuration, see The Docker Compose deployment env.sh configuration file.

Before you begin

Complete Prerequisites for deploying HCL Commerce Version 9.1 with Docker Compose to obtain the required software and prepare the environment database for the deployment.
Review the differences between an authoring and live environment.

Live

A live environment includes the capabilities that are required for a running HCL Commerce production site and serve end-user traffic.

Authoring

An authoring environment, commonly referred to as auth, includes extra capabilities beyond the capabilities of a live environment. In an authoring environment, site administrators or business users can make changes to your store and then test and preview the changes. Once confirmed to be correct, the changes can then be propagated to the live environment. The authoring environment also has workspaces enabled. This workspace feature allows business users fine-grained control over site changes before they are propagated to the live environment. For more information on the authoring environment, see Authoring environment.
Review the available HCL Commerce topologies. The main distinction in topologies depends on the search solution that is user.
Elasticsearch-based search deployment
- Commerce applications:
  - ts-app
  - ts-web
  - tooling-web
  - query
  - Optional: store-web
  - Optional: store
  - Optional: graphql
  - Optional: utils
  - Optional: xc
  - Optional: approval-app
    
    Third-party:
    
    postgresql
  - Optional: nextjs-store
- Data applications:
  - Commerce Elasticsearch-based search:
    
    nifi
    
    data-query
    
    ingest
    
    registry
  - Third-party:
    
    elasticsearch
    
    zookeeper
    
    redis
Solr-based search deployment
- Commerce applications (auth environment):
  - ts-app
  - ts-web
  - tooling-web
  - search_master
  - redis (third-party)
  - Optional: store-web
  - Optional: store
  - Optional: graphql
  - Optional: utils
  - Optional: xc
  - Optional: cache-app
  - Optional: approval-app
    
    Third-party:
    
    postgresql
  - Optional:orchestration-app
- Commerce applications (live environment):
  - ts-app
  - ts-web
  - tooling-web
  - search_repeater
  - search_slave
  - redis (third-party)
  - Optional: store-web
  - Optional: store
  - Optional: graphql
  - Optional: utils
  - Optional: xc
  - Optional: cache-app
  - Optional: approval-app
    
    Third-party:
    
    postgresql
  - Optional:orchestration-app
Note: If you want to deploy Next.js with Solr search, please obtain the HCL_Commerce_Config_9.1.16.1.zip. Unzip to a folder, follow the runtime\README.md to build customized docker images for next.js-store-app, store-web, tooling-web and ts-app, and use the customized docker images to setup your environment.

About this task

This section provides a method for deploying an authoring and live environment by using native Docker Compose scripts. Use this method to learn and understand how the authoring and live environments interact. You can also use this method to explore the different application topologies that are required for the various combinations of HCL Commerce solutions that are available. When you are ready to create a production environment to serve end-users, you will want to build a more complex system, for greater and more fine-grained control over your deployment.

For more information on planning your production environment, see  Planning your production environment.
For more information on the various production environment topologies, based on the HCL Commerce search and store solutions, see HCL Commerce production environment overview.
To explore the deployment in greater detail, or for a finer control over your deployment, you can opt for a custom manual deployment. With this method you can configure your Docker Compose deployment configuration (docker-compose.yml) and Docker environment (.env) files manually, create custom Docker images for your deployment, and implement your own data persistence.

Procedure

Prepare your persisted volumes.
The /volumes/ directory contains all of the persisted files for your deployment.
For a description of the /volumes/ directory, and its contents see The Docker Compose deployment /volumes/ directory structure and contents.
To prepare your persistent volumes directory:
1. Optional: Set up an Network File System (NFS) share for the Assets Tool persistent volume. This is only required if you are using the Assets Tool functionality for both the authoring and live environments.
2. Set file permission for your persistent volumes.
  Some volumes are mounted to your running containers and require write permissions.
  Recursively set write access to /volumes/ to ensure that it and all of the contained sub-directories are writable.
3. Place any required files into their respective /volumes/ directories.
  - Database drivers for Oracle databases.
  - Third party or self-signed certificates.
  - LDAP configuration.
  - The Google Analytics service account file.
Configure your deployment and its environment through modification or replacement of the env.sh configuration file.
1. Open the env.sh file for editing.
2. Modify the environment variables and deployment parameters to reflect the environment that you want to be deployed.
  For more information on the env.sh configuration file, and specific deployment topology requirements, see The Docker Compose deployment env.sh configuration file.
  Note: The env.sh configuration file now contains additional options for enabling integrations and HCL Commerce features:
  - IBM MQ integration
    The integration configuration of WebSphere Application Server for IBM MQ integration is simplified and automated. Provide the details of your integration within your deployment configuration.
    For more information, see Integrating IBM MQ with HCL Commerce.
  - Marketplace feature
    The Marketplace feature of HCL Commerce was introduced in 9.1.10.0. Due to its relatively early state of development, it is disabled by default, unless manually enabled before deployment.
    For more information on enabling the Marketplace feature, see Enabling HCL Commerce Marketplace functionality within a Docker-based deployment.
3. Save a backup copy with a descriptive name if you want to deploy or tear down this configuration at a later time.
Automatically generate the deployment Docker Compose file and Docker environment file, and start the deployment.
Run the deployment bash script.
In a command prompt, run ./deploy.sh.
The script produces the final Docker Compose file and Docker environment file based on the specified configuration in env.sh, and brings your deployment online.
The final Docker Compose file will be docker-compose-commerce.yml for the HCL Commerce deployment, or docker-compose-data.yml for HCL Commerce Search with Elasticsearch.
The deployment will set the project to commerce, so the created Docker services will have commerce_ prefix. For example, commerce_txn_1.
Important: The deployment must be repeated if your HCL Commerce topology requires the deployment of the separate Elasticsearch-based solution. See, Deploying HCL Commerce Search with Elasticsearch.
Verify that all the containers are up and healthy.

Results

The deployment is created, and started. You can now interact with each running HCL Commerce service, and explore each HCL Commerce solution.


Service	URL
Management Center for HCL Commerce	https://`commerceHost`:8000/lobtools
Emerald B2C store	https://`commerceHost`:6443/Emerald
Sapphire B2B store	https://`commerceHost`:6443/Sapphire
Nextjs Ruby store	https://`commerceHost`:6443/
Aurora B2C store	https://`commerceHost`:8443/wcs/shop/en/auroraesite
Aurora B2B store	https://`commerceHost`:8443/wcs/shop/en/aurorab2besite
Query Service Swagger UI	https://`searchHost`:30921/search/resources/swagger-ui.html#/
Ingest Service Swagger UI	https://`searchHost`:30801/swagger-ui.html#/
Nifi	http://`searchHost`:30600/nifi
Nifi Registry	http://`searchHost`:30400/nifi-registry

What to do next

To tear down the HCL Commerce deployment in a Linux environment, you can run the teardown script.

./teardown.sh

If you are deploying HCL Commerce Search with Elasticsearch on Windows without a bash environment to run the teardown script, you can use the following command to tear down the deployment.

docker-compose -p PROJECT_NAME -f DOCKER_COMPOSE_FILE down

Note: If you have both commerce and data deployed on the same machine, you must run this script twice with the corresponding env.sh file present.