Deploying customizations with a CI/CD pipeline

Deploy customizations by using a continuous integration and continuous delivery (CI/CD) approach.

Complete the following steps to set up a build machine with the necessary tools to build and deploy customizations.

1. Install Docker.
   Docker is used to install the necessary components and dependencies to set up the Order Hub container only. You do not develop Order Hub customizations within the container. You develop on your local workstation.
2. Install a Node.js version that is compatible to Angular v15 or v18. For more information, see the Angular page Version compatibility. If multiple node versions are required, consider using nvm (for Mac or Linux) or nvm-windows (for Windows).
3. Install Yarn.
4. Install Angular CLI globally by running one of the following commands in a terminal.
   For Angular v15, run the following command.

   npm install -g @angular/cli@15

   For Angular v18, run the following command.

   npm install -g @angular/cli@18

5. On the build machine, set up a destination folder with the Order Hub source code.
   You can get the source code by using multiple methods. For example,

   • Download the developer toolkit and extract the source code. For more information, see step 6.j.
   • Have the Order Hub source code tar file (from the version that was used to perform the customization) available in a repository. Then, clone and extract the tar file to your build machine.

Set up pipelines to download, package, and deploy customizations.

6. Download or extract all customizations from your repository.
7. Overlay the customizations into the destination folder that includes the Order Hub source code.
8. Retrieve the Customization folder, Customization client ID, Customization auth key for each of the tenants where you want to deploy the customizations. For more information, see Enabling the customization menu for a tenant.
9. Set up pipelines to package the customizations.
   For each customized application, configure pipelines to run the following command within the customized application module's root folder (devtoolkit_docker/orderhub-code/<module-name>). Set up a pipeline for each target environment where you want to deploy the customizations. If you plan to deploy to 4 environments, set up 4 pipelines.

   • To deploy customizations for existing applications, set up pipelines to run the following command. Pass the corresponding build-target and customization-context-root parameters in the following yarn call.

     yarn package-customization --build-target=build-merged-<environment> --customization-context-root=<customization_folder>

     For example,
     • To package the buc-app-order module for deployment to the dev1 environment:

       c:\devtoolkit_docker\orderhub-code\buc-app-order> yarn package-customization --build-target=build-merged-dev1 --customization-context-root=/buc-app-customization/T3R4fagafd45aadfaffasf
       

     • To package the buc-app-inventory module for deployment to the qa3 environment:

       c:\devtoolkit_docker\orderhub-code\buc-app-inventory> yarn package-customization --build-target=build-merged-qa3 --customization-context-root=/buc-app-customization/dbU2K1u4seqrRKwBZTyMp1lUJwqQkJ5A
       

   • To deploy new applications, set up pipelines to run the following command.

     yarn build-<env>

     For example,
     • To package the my-custom-app1 module for deployment to the dev1 environment:

       c:\devtoolkit_docker\orderhub-code\my-custom-app1> yarn build-dev1

     • To package the special-custom-app2 module for deployment to the qa3 environment:

       c:\devtoolkit_docker\orderhub-code\special-custom-app2> yarn build-qa3

10. Set up pipelines to deploy the customizations.
    For each customized application, configure pipelines to run the following command within the customized application module's root folder (devtoolkit_docker/orderhub-code/<module-name>. Set up a pipeline for each target environment where you want to deploy the customizations. If you plan to deploy to 4 environments, set up 4 pipelines. The target environment is determined by the client-id and client-secret. Each environment has a unique client id-secret pair.

    yarn orderhub-cli publish-customization --client-id=<clientId> --client-secret=<clientSecret> --package-name=<module-name>

    Required Parameters:

    • --client-id - The customization client ID. For more information about how to get the ID and secret, see Enabling the customization menu for a tenant.
    • --client-secret - The customization client secret.
    • --package-name - The module folder under the build directory that contains the files to upload. This value corresponds to the module name, such as buc-app-order.

    Optional Parameters:

    • --orderhub-hostname - The hostname for the Order Hub API server. Defaults to app.omsbusinessusercontrols.ibm.com.
    • --proxy-host - The proxy hostname and port in case the build machine does not have access to orderhub-hostname directly.
    • --package-only - Indicates whether to build the customization asset zip only. Defaults to false.
    • --publish-only - Indicates whether to upload a prebuilt customization package. Defaults to false. If set to true, you must also specify the package to publish by using the --package-name parameter. For the --package-name, specify the path to <build-dir>/<package-name>.zip. For example,

      --publish-only=true --package-name=./dist/buc-app-order.zip

    • --build-dir - The directory that contains the compiled customization asset. Defaults to dist.