Custom package repository structure

The HCL Commerce Build tool (WCB tool) can build applications for all four server types: the Transaction server, Store server, Search server, and Customization server. An example shows how you can build your own extensions using the HCL Commerce Build tool.

After you run the HCL Commerce Build tool to build packages, a ZIP package is generated for each server component. A single package includes only files for a single server component.

Important: 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.

Customization deployment directory structure and Logic

At a high-level, HCL Commerce Version 9.1 uses build and deployment logic, that is based on the HCL Commerce build and deployment tool from earlier versions. The build logic remains similar to the build processes from earlier versions. The deployment logic however, is now separated from the build processes to better function with Docker technology.

Within HCL Commerce, Docker technology is used to improve the efficiency of operations. However, due to the structure of the included Docker containers, the packages that you need to create to deploy custom code and other files into these containers need to be organized according to a specific file structure. Your packages also need to be built and deployed using specific logic.

When you are packaging your custom code and other files for deployment to Docker containers, you must use the HCL Commerce build process to ensure that your packages can be deployed successfully to your HCL Commerce. For more information about the actual HCL Commerce build process, see Configuring and building packages.

When you are packaging files for your server containers, you need to build separate deployable packages for each server type. You can build a package with the HCL Commerce build process for the following server types.

Transaction server(ts-app)
Search server (search-app)
Store server (crs-app)
Customization server (xC-app)

The package for each server type has a fixed file structure, which is used with pre-defined logic to apply customizations and other changes when HCL Commerce builds custom packages to use to create Docker images for updating an environment.

Repository structure for building server packages

After you run the WCB utility to build a customization package, you get a compressed ZIP file with the packaged code.

Review the information in the following topics about what is included in the package and what happens to the files when you deploy to your Docker images.

Transaction server: Repository structure for building Transaction server (ts) packages
Store server: Repository structure for building Remote stores (crs) packages
Transaction server: Repository structure for building Search server (search) packages
Customization server: Repository structure for building Commerce UE (xc) packages

Building database asset packages

For data, you do not need to specify the assets to be built. You only need to put your data files into related directories (sql, xml, dataload, acug, acp, acpnls). For the details of file structures, see HCL Commerce Build tool repository structure.

General deployable package file structure

Within a deployable package for any server type, four standard folders can be included at the root level of the package:

Code
Customization code should be included within this folder. Include your code within JAR or WAR files.
Config
Configuration changes should be included within this folder.
(Optional) Certs
Include custom certificates within this folder.
(Optional) DeployScripts
Include custom deployment logic in this folder, such as logic for defining how customizations should be deployed. If you do include this folder, the applyCustiomization.sh file will search the folder for a applyDeployScripts.sh file. This file is then used to identify and process any extended deployment logic that you define, such as for handling any files and folders that you include in addition to the standard four root folders.

When you are building a package, the HCL Commerce build scripts package your custom code within the Code and Config folders. These two folders are created by default when your run a build process to create a deployable package. The subfolder structure for the Code and Config folders are similar across packages for each server type.

When your run a build process, the optional Certs and DeployScripts folders are not created by default. If you need to deploy certificates to a server or define custom deployment logic, update the HCL Commerce build scripts to generate these folders and to package your corresponding files within these folders.

When the HCL Commerce build process runs to build a custom package, the process calls the applyCustomization.sh file. If the file is configured to generate the optional folders, the build process will create the folders and use default logic for how to handle any files or other assets that are included within the folders. The sub-folder structure for these folders is expected to match the following structure:

For the Certs folder, include the following file structure for including your assets:
```
Certs
  component-name
    CertificateFilename.json
    Certificate2Filename.json
```
Where component-name is the name of a component where the certificate needs to be applied. You can include multiple certificates for a component. Each certificate needs to be defined as a JSON file. For more information about how to define certificate information in a JSON file, see Managing certificates manually
For the DeployScripts folder, include the following file structure for including your assets:
```
DeployScripts
  component-name
    applyDeployScripts.sh
    
```
Where component-name is the application component (ts-app, search-app, crs-app, or xc-app). For each additional component that you include in your deployable package, include a directory for that component and an applyDeployScripts.sh file for defining how the component assets are to be deployed.

Building a custom Docker image with a deployable package

When you need to build a custom Docker image, you need to build the appropriate default Docker image with your custom deployable package. The high-level process for creating this custom Docker image involves the following process:

Create a folder named CusDeploy
Extract your custom package within the CusDeploy folder.
Create a file named Dockerfile on the same path as the CusDeploy folder, such as within the same parent folder.

Write your Dockerfile to include the following content: HCL Commerce Version 9.1.14.0 or later

FROM Target_Component_Docker_Image
COPY --chown=comuser:comuser CusDeploy /SETUP/Cus
RUN /SETUP/bin/applyCustomization.sh
optional_commands

For releases of HCL Commerce 9.1.0.0 to 9.1.13.0:

FROM Target_Component_Docker_Image
COPY CusDeploy /SETUP/Cus
RUN /SETUP/bin/applyCustomization.sh
optional_commands

Run the Docker build command from the same folder where your Dockerfile is placed:
```
docker build -t new_Docker_image_name:tag .
```

Customizing the Certs folder

Certs and DeployScripts are not mandatory folders in the package. You can include third-party certificates for integration purposes in the Certs folder. HCL Commerce Version 9 supports loading third-party certificates from a remote site to a Docker container during startup, and packaging the third-party certificates in the customization package. When you build the customized Docker image, those certificate files are copied to the /SETUP/certs/custom directory.

Customizing the DeployScripts folder

You can include the customized deployment logic in the Deployscripts folder. To package these two folders in the final ZIP file, customize the HCL Commerce Build Tool scripts. You can package you customized JAR files or scripts to the DeployScripts folder, and write the deployment logic into applyDeployScripts.sh.

Note: Ensure that the commands within the script are compatible with the non-root user implementation.

Sample repository structure

These examples are for reference only, intended as a starting point to help you to set up your own build environment.

The following WCB_sample.zip provides sample properties files that you can use as a reference to better understand what you need to configure. The WCB_sample.zip package also contains the xC sample.

WCB_sample.zip