Installing ibm-lh-client

The ibm-lh-client package includes convenient utilities and pre-packaged libraries to access the IBM® watsonx.data, and to develop applications that work with the watsonx.data.

watsonx.data Developer edition

watsonx.data SaaS on AWS

watsonx.data on Red Hat® OpenShift®

Before you begin

  • Ensure that you have your entitlement key to access the IBM Entitled Registry. After you obtain the entitlement key from the container software library, you can log in to the registry with the key and pull the runtime images to your local system.
  • Make sure to meet the following system requirements and install the most recent version of Docker or Podman on your system.
    Operating system x86-64 Docker / Podman / Colima installation instructions
    Linux ✓

    Docker

    Podman
    Windows ✓

    Docker

    Podman
    Mac OS x86 ✓

    Docker

    Podman
    Mac with Apple Silicon with Rosetta Emulation  

    Docker

    Colima
    Note: Make sure to meet the prerequisites for installing the watsonx.data client package on Mac with Apple Silicon with Rosetta Emulation.
  • If you are using SUSE Linux, podman is only available for version SLES 15.4. Upgrade the system first (zypper dist-upgrade) before installing the dependencies that are not provided but are needed for the installation of docker or podman.
    • For Docker: sysuser-shadow in SLES 12.5 and catatonit in SLES 15.5.
    • For Podman: fuse-overlayfs in SLES 15.4.
    Note: Packages can be downloaded from the official site.
  • Ensure to add the podman-plugins for the DNS server of the Podman network to work properly.
    yum install -y podman-plugins

    For SUSE, install cni-plugin-dnsname instead.

    If you add the podman-plugins after you start the watsonx.data service, delete the Podman network ibm-lh-network and restart the watsonx.data service.
    Tip: Podman provides a Docker-compatible command-line front end. You can alias the Docker CLI with the alias docker=podman shell command.
Important: It is important to set up and run the client utilities as a non-root user. For more information about granting access to non-root users to work with the container engines, see Manage Docker as a non-root user and Rootless containers using Podman. To ensure user-specific access, each user needs to extract and set up the ibm-lh-client package in a private subdirectory within their own home directory.

Procedure

  1. Set up the installation directory and environment variables
    1. Set up the work directory. 
      mkdir <install_directory>
cd <install_directory>
    2. Set the environment variables: 
      export LH_ROOT_DIR=<install_directory>
export LH_RELEASE_TAG=latest
export IBM_LH_TOOLBOX=cp.icr.io/cpopen/watsonx-data/ibm-lakehouse-toolbox:$LH_RELEASE_TAG
export LH_REGISTRY=cp.icr.io/cp/watsonx-data
export PROD_USER=cp
export IBM_ENTITLEMENT_KEY=<ibm_entitlement_key> 
export IBM_ICR_IO=cp.icr.io
      Note: The environment variable LANG is passed into the containers to support Full width and MBCS characters. If the LANG is not set, the default is considered to be en_US.UTF-8. Update the LH_CLIENT_LANG in etc/local_config.env to change the LANG chosen during installation.
      Note: Use the following table to identify the LH_RELEASE_TAG value:
      Table 1. Release tags with Cloud Pak for Data versions
      Cloud Pak for Data version Service instance version
      4.8.5 v1.1.4 (latest)
      4.8.4 v1.1.3
      4.8.3 v1.1.2
      4.8.1 v1.1.1
      4.8.0 v1.1.0
      The latest tag is set to v1.1.4
      If you are using Docker, run the following command:
      export DOCKER_EXE=docker
      If you are using Podman, run the following command:
      export DOCKER_EXE=podman
  2. Pull the watsonx.data client package and copy it to the host system: 
    $DOCKER_EXE pull $IBM_LH_TOOLBOX
id=$($DOCKER_EXE create $IBM_LH_TOOLBOX)
$DOCKER_EXE cp $id:/opt - > /tmp/pkg.tar
$DOCKER_EXE rm $id
id=
  3. Extract the watsonx.dataclient pkg.tar file in to the /tmp directory. Verify that the checksum is correct by comparing the checksum in bom.txt and the cksum command output. For example, run the following command: 
    tar -xf /tmp/pkg.tar -C /tmp
cat /tmp/opt/bom.txt
cksum /tmp/opt/*/*
tar -xf /tmp/opt/client/ibm-lh-client-*.tgz -C $LH_ROOT_DIR
  4. Authenticate with the registry: 
    $DOCKER_EXE login ${IBM_ICR_IO} \
--username=${PROD_USER} \
--password=${IBM_ENTITLEMENT_KEY}
  5. Run the setup script. 
    $LH_ROOT_DIR/ibm-lh-client/bin/setup --license_acceptance=y --runtime=$DOCKER_EXE