v2.1.7+Deploying HCL Universal Orchestrator on premises

The installation package contains scripts, JAR files, and licenses available for download from the MHS portal. When you run the installation scripts, the system automatically validates certificates and verifies all required attributes to ensure a successful setup.

Before you begin

Ensure your environment meets the following requirements:

  • Installation Files: Download the hcl-uno.zip file from the MHS portal. For more information, see My HCLSoftware.

    The zip file contains the following files and folders:
    • bin
      The folder contains the HCL Universal Orchestrator jar file, hcl-uno-VERSION.jar.
    • configuration-files
      The folder contains the uno-install.properties and uno-install.yaml files, which contain mandatory and optional parameters for installation. Specify the required parameter values in either file and run the installation (2), or run the install command with the required parameters as described in the procedure steps.
    • iso-swid
      The folder contains the hcltechsw.com_HCL_UnO.swidtag file, an XML file for inventory tracking.
    • licenses
      The folder contains notices and license agreements associated with HCL Universal Orchestrator.
    • storage
      The folder contains two subfolders:
      • event-manager: Contains the jar files for the default event-manager plug-ins.
      • job-plugins: Contains the jar files for the default job plug-ins.
    • uno-install.sh/ uno-uninstall.sh: The scripts to install/uninstall the HCL Universal Orchestrator instance on Unix operating systems.
    • uno-install.ps1/ uno-uninstall.ps1: The scripts to install/uninstall the HCL Universal Orchestrator instance on Windows operating systems.
  • Operating System: Use a system running a 64-bit version of Windows or Linux.
  • Java: Installed Java 21 or higher (JDK 21).
  • Hardware: 4 GB of RAM and two CPUs (8 GB of RAM is recommended for optimal performance).
  • Database: MongoDB v 8 OR Azure DocumentDB (formerly known as Azure Cosmos DB for MongoDB vCore) OR AWS DocumentDB v 5. For more information, see MongoDB documentation or Azure Cosmos DB or AWS Document DB.
  • Messaging system: Apache Kafka v 3.9 or later OR Redpanda v 25.3 or later. For more information see, Apache kafka documentation or Repanda documentation.
  • Security: Enabled an OIDC provider for authentication. To setup keycloak as the OIDC server, see keycloak documentation.
  • Configure a load balancer or a Domain Name System (DNS) mechanism. To ensure uninterrupted service, install multiple instances of HCL Universal Orchestrator. Then, provide the instance details in the load balancer to create an active-active setup.
  • Permissions:
    • A dedicated standard account with ownership permissions restricted to the folder where the JAR file is located. All the required commands must be run as this user and never as administrator.
    • Local Administrator rights are required for the installation to register services and handle certificates.

About this task

The installation step creates an HCL Universal Orchestrator instance on the local system, tests the connection, generates or copies the certificates, and completes all the setups needed for it to run successfully.

After you successfully install the HCL Universal Orchestrator instance, the system creates a directory named .uno by default. The mandatory and optional parameters that you can set to configure the installation are described in the following procedure. The system saves all parameters for setting up the HCL Universal Orchestrator instance into a single file called uno.properties, which is stored in the .uno directory.

To ensure an uninterrupted connection, install multiple HCL Universal Orchestrator instances connected to the same MongoDB and Kafka clusters. You must configure a load balancer or a Domain Name System (DNS) mechanism to distribute the workload across these instances.

Procedure

  1. Extract the contents from the downloaded hcl-uno.zip file.
  2. Open the command line and run the command as follows:
    Note:

    To run the installation process as a daemon, you must open PowerShell with local administrator rights.

    To run the HCL Universal Orchestrator instance as a daemon, you must first install the application to create the management scripts. After the installation, run the daemon-install.sh script. For more information, see Managing the HCL Universal Orchestrator on-premises instance by using scripts.

    ./uno-install.sh [Mandatory parameters=value] [Optional parameters=value]
    uno-install.ps1 [Mandatory parameters=value] [Optional parameters=value]
    The details for mandatory and optional parameters as follows:
    Table 1. Mandatory Parameters
    Parameter Description
    --licenseAccepted Confirm the acceptance of the software license agreement. Supported value is yes.
    --sslFolder Specify the path to the folder containing the valid enterprise SSL certificates. For more information, see Managing TLS/SSL certificates.
    --dbUrl or -dbu Specify the connection URL for the MongoDb instance.
    --dbType or -dbu Specify the database type and the supported value is mongodb.
    --dbName or -dbn Specify a name for the MongoDb database.
    --dbUsername or -dbUn Specify the username and password to access the MongoDb instance.
    dbPassword or -dbp
    --kafkaUrl or -ku Specify the connection URL for the Kafka instance.
    --kafkaUsername or -kn Specify the username and password to access the Kafka instance.
    --kafkaPassword or -kp
    --oidcServer Specify the URL for the Oidc server instance.
    --oidcClientId Specify the unique identifier used by the UnO instance to authenticate itself with the OIDC provider.
    --oidcCredentialSecret Specify the client secret associated with the OIDC Client ID. This value is used by the application to authenticate itself securely with the OIDC server.
    --additionalCerts Define the file path to the certificates required for integrating external services with the HCL Universal Orchestrator instance.
    --passphrase Specify a passphrase of at least 8 characters. You can use alphanumeric and wildcard characters. This passphrase is used for AES encryption of private keys, the Root CA, and sensitive configuration parameters in the uno.properties file.
    --adminName Specify the user name of the primary administrator.
    Note: The installation script prompts for any missing mandatory attributes before proceeding.
    Table 2. Optional parameters
    Parameter Description
    --dataDir or -d You can specify the path to the folder to create the directory.
    Important: You must specify the path with a double backslash to install the application in the correct location. For example, use C:\\Users\\john\\media.
    If no path is given, a directory with files and folders is created as follows:
    home/user_name/.uno
    c:\Users\user_name\.uno
    --sessionTimeout Specify the duration of inactivity (in minutes) after which a session is automatically closed.
    --logoutEnabled Specify whether the logout option is visible and functional within the user interface. Supported values are true or false.
    --dbTls Specify whether the TLS encryption is enabled for the database connection or not. Supported values are true and false.
    --dbTlsInsecure Specify whether the certificate validation must be skipped or not. Supported values are true and false.
    --KafkaTls Specify whether the TLS encryption is enabled for the messaging connection or not. Supported values are true and false.
    --kafkaSaslMechanism Specify the security mechanism used to authenticate the application with the Kafka brokers. Supported values are PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, GSSAPI, and OAUTHBEARER.
    --kafkaJaasConfig Specify the Java Authentication and Authorization Service (JAAS) configuration string used for SASL authentication.
    --kafkaSecurityProtocol Specify the protocol used to communicate with Kafka brokers. Supported value are PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL.
    --kafkaTlsInsecure Specify whether the certificate validation must be skipped or not. Supported values are true and false.
    --kafkaKerberosSvc Specify the Kerberos service name (Service Principal) under which the Kafka brokers are registered. This parameter is only used when --kafkaSaslMechanism is set to GSSAPI.
    --kafkaTopicReplicas Specify the replication factor for the Kafka topics created by the application.
    --oidcTlsVerification Enables both certificate validation and hostname verification. You can use the config.certificates.additionalCASecrets parameter to add a secret for the OpenID Connect (OIDC) server CA. This parameter only applies when enabled is set to true. Supported values are:
    • none: All certificates are trusted and hostname verification is disabled.
    • required: Certificates are validated and hostname verification is enabled.
    • certificate-validation: Certificates are validated and hostname verification is disabled.
    --enableGenai Specify whether the generative AI feature is enabled. The default value is true.
    --genaiSvcUrl Specify the connection URL for the generative AI service.
    --genaiBetaKey Specify the beta key required to authenticate with the generative AI service.
    --genaiProxyHost Specify the hostname of the proxy server used to route the generative AI connection.
    --genaiProxyPort Specify the port number of the proxy server for the generative AI connection.
    --genaiProxyUsername Specify the username an password required to access the generative AI proxy.
    --genaiProxyPassword
    --genaiMaxUserPrompts Specify the maximum number of user prompts allowed for the generative AI.
    --genaiMaxActions Specify the maximum number of actions permitted per generative AI conversation.
    --genaiMaxUnattendedActions Specify the maximum number of unattended actions the generative AI is allowed to perform.
    --jvmXms Specify the minimum heap memory limit for the Java Virtual Machine.
    --jvmXmx Specify the maximum heap memory limit for the Java Virtual Machine.
    --port Specify the port number of the configured HCL Universal Orchestrator server.
    --no-wait Specify whether the installation process waits to print the application access URLs. Supported values are true and false. If you specify false, the installation completes without waiting to print the URLs used to access the UI, API, and metrics.
    --publicUrl Specify the public URL or the endpoint managed by your load balancer that routes traffic across the cluster of replicas.
    You can specify mandatory and optional parameters by using a configuration file in either .properties or .yaml format. The installer supports hierarchical configurations in uno-install.yaml as well as key-value pairs in uno-install.properties. If a parameter is defined in multiple places, the installer resolves the value using the following priority order (from highest to lowest):
    • Command-line arguments
    • Configuration file values
    • Interactive prompt defaults
  3. Press Enter.
    Note: To ensure an uninterrupted connection, install multiple HCL Universal Orchestrator instances on separate servers connected to the same MongoDB and Kafka clusters. Repeat the installation process from step 1 for each additional instance. Provide the details to the load balancer that you set up to create an active-active setup.
    Restrictions:
    • Connectivity to AI Pilot and Agentic AI Builder is not supported.
    • Multitenant environment is not supported.
    • The process does not install the HCL UnO agent or Orchestration CLI. These packages must be downloaded from the MHS portal because the Download Center is deactivated for on-premises installation.

      For more information, see Installing HCL UnO agent and Installing and authenticating the Orchestration CLI.

Results

The system displays the following URLs for access:
  • UI: https://localhost:8442/ui/
  • Swagger: https://<ip_address>:8442/q/swagger-ui/
  • Metrics: https://<ip_address>:8442/q/metrics/
Examples:
  1. Run the command as follows to install HCL Universal Orchestrator with all mandatory parameters:
    .\uno-install.ps1 --licenseAccepted=yes  --dbUrl='mongodb://localhost:27017/?compressors=abcd' --dbType='mongodb' --dbName='uno' 
--dbUsername='usera' --dbPassword='wauserabc' --kafkaUrl='hcl-uno-kafka-aio-0:9092' --kafkaUsername='userb' --kafkaPassword='userxyz' 
--oidcServer='https://localhost:8843/realms/uno' --oidcClientId='uno-service' --oidcCredentialSecret='7LVAISK187GTFKY2JK2NNAGVFEJISZCRF' 
--additionalCerts='C:\Users\johnvar\uno-additional-certs' --no-wait=false --dbTls=false --kafkaTls=false --publicUrl='https://myuno.com'
  2. Run the command as follows to install HCL Universal Orchestrator with the uno-install.yaml configuration file saved at C:\Users\username\Desktop\uno:
    .\uno-install.ps1 --configFile="C:\Users\username\Desktop\uno\uno-install.yaml"
  3. Run the command as follows to install HCL Universal Orchestrator by overriding the port value specified in the configuration file:
    .\uno-install.ps1 --configFile="C:\Users\username\Desktop\uno\uno-install.yaml --port=7888"