Installing and Configuring Clara from V1.0.0.6 with Docker

Checking system prerequisites

Before starting to install Clara, you must check the following system prerequisites:

  1. Verify that Docker and Docker Compose are installed, configured, and ready to use. For the required version, see: System Requirements.  

If you don't have Docker and Docker Compose already installed, see: Installing Docker and Docker Compose.

  1. Clara requires some values to be set for ulimit parameter, for Linux OS. See: How to verify and set ulimit parameter.

  2. Verify the available virtual memory. See: How to verify and set the available virtual memory.

  3. If you are installing Clara on RHEL or CentOS distros, SELinux must be set to Permissive or Disabled. See: How to set SELinux to permissive.

  4. A License Server associated to your license entitlement (License ID) must be created. The License Server and the License ID must be specified during the installation procedure. For details, see What is the HCL Software License & Download Portal. The license entitlement and expiration date depend on the type of license you have purchased (if product, bundle, or trial).

  5. If you want to integrate Clara in the Dynamic Workload Console (feature available from Clara V1.0.0.7), check the SSL certificates of the Dynamic Workload Console. If the default certificates have been replaced by custom certificates, during Clara installation procedure you must replace the value of the DWC_KEY parameter in the <BUILD_DIR>/clara/config/Clara-WA.env.TEMPLATE file accordingly. See below the section about Customizing environment files.

 

Note: From Clara V.0.0.6, the Autobot license is no longer required.

Installation procedure

To install and configure Clara, run the following procedure.

 

  1. From HCL License Portal download the appropriate Clara installation package. Depending on your license type, you have two different options:

Each option is available with 2 different types of installation packages: online and offline.

 

Use the online installation package to build Clara images directly on your machines. This type of package requires a working Internet connection.

Use the offline installation package if the machine does not have an Internet connection or if you do not want to build Clara.

 

  1. Extract the content of the tar.gz file into <BUILD_DIR>, a directory of your choice, using one of the extraction tools available on your system or downloadable from the Internet. The tool you use must be able to keep the file permissions on the extracted files.

  1. This is an optional step. If you skip this step, the installation script will ask you to provide the basic customization information during the installation process. Otherwise, to fully customize Clara interaction with your Workload Automation environment, or to integrate Clara in the Dynamic Workload console, you must properly modify the <BUILD_DIR>/clara/config/Clara-WA.env.TEMPLATE file. See below the section about Customizing environment files.  If you want to enable Clara interaction with multiple Workload Automation environments, see Managing multiple Workload Automation environments.  

  2. If you want to change default Clara credentials before building in Docker, see Customizing Clara credentials.

  1. To install Clara on Linux operating system, the user must have read and write permissions for the  <BUILD_DIR>  directory. Also, the user must have execute permission for Docker commands. This means that the user must be a member of sudoers group or Docker group. If the user is a member of sudoers group but not of Docker group, the installation script must be run with sudo.

  1. Open a bash shell and get ready to install Clara.

  1. If it is the first time you install Clara, or you need to update Clara images, you must first build Clara images.  You can skip this step if you are not installing Clara for the first time or the images are locally available.

Change the directory to <BUILD_DIR> and extract the content of clara-img.tar.gz file:

cd <BUILD_DIR>

tar xvfz clara-img.tar.gz

Build Clara images by running the command:

clara-img/clara-build.sh -p -i ALL 2>&1 | tee clara-build.log

 

Note: To run the above command, an active internet connection is required. In case this is not possible, you can build Clara images on a different Linux server with Docker and an internet connection. See Building Clara images on a different server.

 

If you have built images locally, you can skip directly to the next step.

If you have built images on a remote server, ensure all required tar.gz files have been copied locally under <BUILD_DIR> directory and run the following command:

./clara.sh --load-images 

  1. Proceed with Clara installation. From the <BUILD_DIR> directory, run the command:

    2. ./clara.sh --install --install-path <install_path>

    where <install_path> is the installation directory of your choice (default value is /opt/hcl).

    When you launch the command, you will be required to enter:

     

    See Clara.sh command usage if you want to skip the OS prerequisites check, all variable prompts and use defaults (defaults will be loaded from .env file, if present, in the installation or local path).

    For example, if you pass the following parameters to the installation script:

    --skip-check-prereq --skip-var-prompts

    and a valid .env file is present in the installation or local path, the installation will be completely unattended.

  1. From the installation directory, activate and configure Clara by running the following command:

    2. ./clara.sh --load-project <prj>

    where <prj> can be:

    IWA   IBM Workload Automation

    HWA   HCL Workload Automation

    IWAz  IBM Workload Automation for z

    HWAz  HCL Workload Automation for z

  2. As the installation script starts, if you haven't previously customized  the <BUILD_DIR>/clara/config/Clara-WA.env.TEMPLATE  file (see step 3), you are required to provide information to enable Clara interaction with your target Workload Automation environment. Press Enter to accept the proposed default values.

  3. The installation script checks the prerequisites (unless you have specified the --skip-check-prereq parameter), runs the installation process, and verifies its successful completion.

 

 

Post installation steps

When the installation is completed, you can access Clara web interface at the following link https://<IP:PORT>/Clara/  where:

The installation script generates two Clara users:

As you start chatting with Clara, you must define credentials for the product environments you want to manage with Clara. The User Credential Manager component will help you map your product environment credentials with your Clara credentials (each Clara user can manage his own Workload Automation credentials). For additional details, see Managing User Credentials.

 

Use the Keycloak administration console to define new Clara users, new roles, or change default passwords. You can access Keycloak administration console https://<IP:PORT>/keycloak/auth/admin by using the following default credentials:

You can change the Keycloak default password or the default SSL certificates. For details, see Configuring Security.

For security reasons, you are recommended to generate a custom Keycloak Client Secret, in place of the default one provided in your environment TEMPLATE file. See How to set a custom Client Secret.

 

You can also interact with Clara by using messaging tools such as Slack and Sametime. For the required configuration steps, see Installing Adapters for Messaging Tools.

 

To start/stop Clara containers and to start/stop Clara services, see clara.sh command options below.

 

After Clara installation, if a re-configuration is needed (for example to integrate Clara in the Dynamic Workload Console), or you want to enable Clara interaction with additional Workload Automation environments, you must modify the .env file created during the installation process and located in the folder <BUILD_DIR>/clara. Then, run the following command to activate the updates: clara.sh --up --nc

For details, see: Managing multiple Workload Automation environments.

 

 

Customizing environment files

Both for Workload Automation and Workload Automation for Z, before starting Clara installation, to fully customize your Clara environment modify the  <BUILD_DIR>/clara/config/Clara-WA.env.TEMPLATE file by providing the following information:

Common properties

 NGINX_PORT

 TCP/IP Port to use with Clara [Default: 443]

 NGINX_CERTS

 Path where nginx certificates for Clara are stored [Default: ./nginx. If Clara is installed in the default installation folder, the default path of the certificates is: /opt/hcl/clara/nginx  ]

 CLIENT_SECRET

 Client Secret to access Keycloak [Default: 214c76c5-f726-482b-92b6-2f5586c7bbe1]

Workload Automation properties

 PROJECT

 HWA for HCL  Workload Automation

 IWA for IBM Workload Automation

 HWAz for HCL Workload Automation for z

 IWAz for IBM Workload Automation for z

 WA_ENV_NAME

 Mnemonic name of the Workload Automation environment [Default: WA-PROD]

 WA_SERVER_NAME

 Only for WA: hostname of the Workload Automation server (MDM) [Default: wa-server]. You can skip this settings if you are configuring Workload Automation for z

 WA_SERVER_PORT

 Only for WA: HTTPS port where WA server (MDM) is listening [Default: 31116]. You can skip this settings if you are configuring Workload Automation for z

 WA_CONSOLE_NAME

 Hostname of the Workload Automation Web console [Default: wa-console]

 WA_CONSOLE_PORT

 HTTPS port of the Workload Automation Web console [Default: 16311]

 WA_ENGINE_NAME

 Name of the engine definition within Workload Automation [Default: engine]

 WA_LIC_SERVER_NAME

 Hostname of the License Service provided by HCL [Default: https://hclsoftware.compliance.flexnetoperations.com/instances/]

 WA_LIC_ID

 Unique ID of Clara License

 WA_TKT_URL

 Url to the Service Platform for Ticketing [Default: https://servicenow.com]

THREADPULL_SIZE

The number of monitoring processes that Clara can manage simultaneously [Default: 50] - Optional parameter

 SMTP_HOST

 Fully qualified hostname of the SMTP Server that will be used by Clara to send email notifications [Example: smtp.gmail.com]

 SMTP_SENDER

 Used to send email to the recipient specified in Clara Credential Manager [Example: username@gmail.com]  

 SMTP_SENDER_PASSWORD

 Used to authenticate the SMTP_SENDER

 SMTP_AUTH_PROTOCOL

 The authentication type defined in the SMTP_HOST server. Can be TLS or SSL [Default:TLS]

 SMTP_PORT

 The port of the SMTP mail server  [Example: 465 for gmail]

Properties for HERO integration

 HERO_IP

 HERO server IP address. For  WA users only (not WAz).

 HERO_PORT

 HERO server Port. For  WA users only (not WAz).

 HERO_SECRET

 HERO client secret to connect: "CLIENT-SECRET-CONFIG". For  WA users only (not WAz).

 HERO_CLIENT_ID

 HERO nginx client ID: "nginx". For  WA users only (not WAz).

 HERO_REALM

 HERO realm info for the connection: "hero". For  WA users only (not WAz).

 HERO_URL

 Landing page of HERO if not installed: https://www.hcltechsw.com/products/hero/offerings/hero-workload-automation. For  WA users only (not WAz).

Properties for language translation

TRANSLATION_SERVICE

Can be: "google", "azure", or "hcl".

TRANSLATION_SERVICE_URL

The base URL of the translation service (not needed for Google Cloud). By default, for HCL Translation Service it is: http://localhost:5000.

GOOGLE_APPLICATION_CREDENTIALS

For Google Cloud only. The path to the json file that stores Google Cloud credentials. Default value is: /etc/google/credentials.json.

GOOGLE_CREDENTIALS

For Google Cloud only. The path to Google credentials file under google folder). Must be: ./keys/google_generated_key.json

AZURE_SUBSCRIPTION_KEY

For Azure only. The Microsoft Azure subscription key: "YOUR_SUBSCRIPTION_KEY".

AZURE_LOCATION

The Microsoft Azure region. It is required if using a Cognitive Services resource. Default value is: "switzerlandnorth".

SUPPORTED_LANGUAGES

The subset of languages you want to be available in Clara, in ISO 639-1 format. If  TRANSLATION_SERVICE is "hcl", this parameter is ignored. Default value is: ["it","fr","pt","es","de"].  

Properties to integrate Clara in the Dynamic Workload Console

DWC_KEY

The Dynamic Workoad Console certificate. In  Clara, it is set to the following default value (that is the default certificate of the Dynamic Workload Console):

 "-----BEGIN CERTIFICATE-----

MIIB8TCCAVqgAwIBAgIEUKNa0zANBgkqhkiG9w0BAQUFADA9MQswCQYDVQQGEwJV

UzEMMAoGA1UEChMDSUJNMQwwCgYDVQQLEwNUV1MxEjAQBgNVBAMTCVNlcnZlck5l

dzAeFw0xMjExMTQwODQ4MTlaFw0zMjExMDkwODQ4MTlaMD0xCzAJBgNVBAYTAlVT

MQwwCgYDVQQKEwNJQk0xDDAKBgNVBAsTA1RXUzESMBAGA1UEAxMJU2VydmVyTmV3

MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCkHVMHe7Jwgirp/1CvAutmukIe

aFXGoI5zWECO1wMSNeZEUBZx2ugY6XBvuXHkK6aucCePEK3teSxBD4KTdiPc/Z89

xB7A7jzRRixdxRSKLP9QQxN5LX5WEy8Xt+vEuU6N+PeKaXUuXjiGb7iHNbOvBeAK

lz7h2NNz6wywNu0NNQIDAQABMA0GCSqGSIb3DQEBBQUAA4GBAJttjBMHp5p7taCH

YR3MmWg3d5+RQqQ3Mwsbi2oJvfQdQQs32zvaPNPVk6tm8Sx0Vd61QhElrx39Trur

I1NYWSKCMe1X2XZTnc9zDp9lH0g1cEg2afLdxs60Uv67aomTQHyyRM8P9UVdKAza

pQFg3s/jz4Cdz5hY0HnaUoRdTadc

-----END CERTIFICATE-----"

If the Dynamic Workload Console default certificate has been changed, you must modify this Clara parameter accordingly.

Properties for source docker images

 IMG_PREFIX

 Clara docker image repo prefix when images are not available locally, like: example.com/

 TAG

 Clara docker image tag based on Clara version, optional [Default: latest]

 

 

 

 

Building Clara images on a different server

To build Clara images on a different server, run the following steps:

 

  1. Move clara-img.tar.gz file, available under  <BUILD_DIR> directory, on a Linux server with Docker and an active Internet connection.

  2. Extract the content of the file clara-img.tar.gz

    tar xvfz clara-img.tar.gz

  3. Build Clara images running the command:

    clara-img/clara-build.sh -p -i ALL 2>&1 | tee clara-build.log

  4. Create the archive file with all required docker images that can be imported later.

    5. To build the archive, run the following command:

    clara-img/clara-build.sh -s  2>&1 | tee clara-save.log    

  5. The following files will be generated:

  6. Move the above files under the directory <BUILD_DIR> on the server where Clara will be installed

  7. Remove the clara-img directory, the clara-img.tar.gz file and any file produced. You can also remove the images from docker using the command “docker rmi <name>”.

 

Customizing Clara credentials

If you want to change default Clara credentials before building in Docker, you can edit them inside the following files:

  1. Default admin credentials can be changed inside the “docker-compose.yml” file, in the root docker installation folder.

  1. Default test credentials inside Clara Realm can be edited in the ./keycloak/Dockerfile where you find a reference to add-user-keycloak.sh file, customizing the following two parameters:

 

Installing Adapters for Messaging Tools

You can interact with Clara by using Slack and Sametime messaging tools.

To install the required adapters, run the following procedure:

 

From the  <BUILD_DIR> directory where you extracted Clara installation package, build the adapter image for the adapter that you want to install. Run the command:

 

If you want to install the adapter on the same machine where Clara is installed, run the following steps:

  1. Properly configure the config.properties file containing the adapter properties, located in the following directory:

  2. Start the adapter:  

    3. docker run --env-file resources/config.properties --name clara-slackadapter -d clara-slackadapter:latest    

    docker run --env-file resources/config.properties --name clara-sametimeadapter -d clara-sametimeadapter:latest    

 

If you want to install the adapter on a different machine, run the following steps:

  1. Save the adapter image to a file by running the following command:

  1. Locate  the configuration file containing the adapter properties:

  1. Copy the tar.gz file containing the adapter image and the configuration file to the machine where you want to install the adapter.

  2. Properly configure the config.properties file. For details see:

  1. From the machine where you want to install the adapter, load the image from the file by running the following command:  

  1. From the folder where you loaded the adapter image, start the adapter by running the following command:

where <PATH> is the folder containing the config.properties.file

 

Configuration file for Slack adapter

 auth_token

The token generated by Slack bot

 client_secret

The client secret requested to access Keycloak, as defined in the .env environment configuration file for Clara

 bot_url

In the format <IP>:<PORT>.  IP address and Port of the machine where Clara is installed (if Port is 443, it can be omitted)

 bot_project

Specify WA if the Clara project specified during the installation  is HWA or IWA. Specify WAz if Clara project is HWAz or IWAz.

 timeout_interval

The time (in milliseconds) that the Slack session should stay active while chatting with Clara (default: 200000)

 

Configuration file for Sametime adapter

 sametime_password

Password for Clara Sametime account

 sametime_username

Username for Clara Sametime account

 is_encrypted=false

Encryption flag for Sametime account password. Initial default: false. After the first connection the password is automatically encrypted and the flag will turn on true

 sametime_community_hostname

Sametime community server host name

 bot_host

In the format <IP>:<PORT>.  IP address and Port of the machine where Clara is installed (if Port is 443, it can be omitted)

 client_secret

The client secret requested to access Keycloak, as defined in the .env environment configuration file for Clara

 bot_project

Specify WA if the Clara project specified during the installation  is HWA or IWA. Specify WAz if Clara project is HWAz or IWAz

 bot_language=en

The Sametime language

 is_secured=true

Set it to true for HTTPS connection, false for HTTP

 auth=true

Keycloak enablement flag. Set to false if you want to disable Keycloak.

 

 

 

 

 

 

 

clara.sh command

clara.sh [options]

 

OPTIONS:

 

Help:

   -h                      Help

 

To control Clara services:

   

   --up [up options]                 Create and start Clara container

        where [up options] can be:

        [--nc]                               Specify --nc to get the new configuration from the .env file

        [--noauth]                        Specify --noauth to disable authentication

        [--auth]                            Specify --auth to enable authentication

        [--translation]                  Specify --translation to enable the translation service

 

   --down  [--vol]                      Stop and remove Clara containers and network

                                                Specify --vol to remove also persistent volumes

   --start                                   Start Clara services

 

   --stop                                   Stop Clara services

   

   --join-net                             Link Clara network to WA network when they are both running on the same network

 

   --remove                             Print commands to clean-up Clara containers, persistent volumes and network manually

   

   --print-urls                          Print Clara URLS

 

 Examples:

 

    First Clara start-up:

      ./clara.sh --up

 

    Stop Clara containers:

      ./clara.sh --stop

 

    Start Clara with translation:

      ./clara.sh --up --auth --translation

 

To add a custom Knowledge Base to Clara:

 

   --kb <CSV_file>                Integrate Clara KB with the provided Q&A

                                               <CSV_file>   The CSV file with the KB (use absolute path)

 

To backup and restore Clara persistent volumes:

 

   --backup-volumes             Create a backup file for each Clara persistent volume

   --restore <vol_name> --from-dir <backup_directory>

                                              Restore the volume <vol_name> from the backup stored in

                                              the directory <backup_directory> (use absolute path)

    Examples:

 

    Backup all clara volumes:

      ./clara.sh --backup-volumes

 

    Restore the clara-Etc_data volume taken on 2020-12-09-1439-734236800

      ./clara.sh --restore clara-Etc_data --from-dir /opt/hcl/clara/backups/2020-12-09-1439-734236800

 

To install Clara:

 

   -c, --prereq                        Check Prerequisites (skip any other option if present)

 

   --load-images                    Load Clara images from clara_images.tar.gz(in the same path as this script)

 

   --install                               Install or upgrade Clara

   

   --install-path <path>         Modify install path (default is /opt/hcl)

   

   --load-project <prj>          Install the specified Clara project

                                              Possible values for <prj> are:

                                              IWA     IBM Workload Automation

                                              HWA   HCL Workload Automation  

                                              IWAz   IBM Workload Automation for z

                                              HWAz HCL Workload Automation for z 

                           

   --migrate-data                  Migrate all data from Clara V1.0.0.3 to the current version

                                              (this option runs also the --migrate-cred option)

 

   --migrate-cred                  Migrate environment credentials from Clara V1.0.0.4 or V1.0.0.5 to the current version

 

   --export-db                        Export Keycloak database (data and configurations) inside the container volume:

                                              clara-keycloak_data.

                                              The container path is: /opt/jboss/keycloak/standalone/data/clara-realm-bkp.json

 

   --import-db                         Import Keycloak database (data and configurations) from the container volume:

                                               clara-keycloak_data.

                                               The container path is: /opt/jboss/keycloak/standalone/data/clara-realm-bkp.json

                                               This operation deletes all previous data in Keycloak database

 

   --skip-lic-check                 Pass this parameter to skip license check

                                         

   --skip-check-prereq         Pass this parameter to skip all OS prereq checks

 

   --skip-var-prompts           Pass this parameter to skip all var prompts except prereq checks and use defaults

                                              Defaults will be loaded from .env file if present in the installation or local path.

 

   --remote-hostname <name> Specify Clara hostname, i.e. can be the hostname for Clara external access

   

Steps:

 

  1. Check Clara prerequisites

./clara.sh -c

  1. Load Clara images (run only of you need to import new images)

./clara.sh --load-images

  1. Install Clara. Run the command:

 ./clara.sh --install --install-path /opt/hcl

  1. Configure Clara for Workload Automation. From the installation directory, run:

cd /opt/hcl/clara
./clara.sh --load-project HWA

Note: This step will overwrite the existing Clara Knowledge Base and Smart Actions. If you previously modified the Knowledge Base and don't want to lose your changes, see: Upgrading Clara.

  1. If you are upgrading Clara, before installing the new Clara version, you must export the Keycloak database of your previous Clara version. Run:

./clara.sh --export-db

After Clara installation, run the following commands to import data and configurations from your previous version:

    1. If you are upgrading Clara from V1.0.0.2 or V1.0.0.3, run:

cd /opt/hcl/clara
./clara.sh --migrate-data --import-db

    1. If you are upgrading Clara from V1.0.0.4 or V1.0.0.5, run:

cd /opt/hcl/clara
./clara.sh --migrate-cred --import-db

 

   For unattended installations, add the following options to the above commands:
  --skip-check-prereq --skip-var-prompts