Installing `ibm-lh-client` package

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 on IBM Software Hub

watsonx.data on IBM Cloud®

Before you begin

Entitlement key: Ensure that you have the entitlement key to access your container software in the IBM Entitled Registry. Obtain the entitlement key from the container software library to log in to the registry and pull the runtime images to your local system.

System requirements: Make sure to meet the following system requirements and install the most recent version of Docker, Podman, or Colima 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

Linux:
- If you are using SUSE Linux, Podman is only available for version SLES 15.4. Ensure to upgrade the system (zypper dist-upgrade) before installing the dependencies required to install Docker or Podman. Packages can be downloaded from the official site.
  - For Docker: sysuser-shadow in SLES 12.5 and catatonit in SLES 15.5.
  - For Podman: fuse-overlayfs in SLES 15.4.
- Ensure to add the podman-plugins for the DNS server of the Podman network to work properly.
```
yum install -y podman-plugins
```
- For SUSE Linux, install cni-plugin-dnsname.
Tip: Podman provides a Docker compatible command-line front end. You can alias the Docker CLI with the alias docker=podman shell command.
Windows: You must have a Linux environment like Ubuntu installed in your Windows system to install ibm-lh-client package. For more information, see Docker Engine on Ubuntu or Pod man package for Ubuntu.
Mac with Apple Silicon with Rosetta Emulation: Make sure to meet the prerequisites for installing the watsonx.data client package on Mac with Apple Silicon with Rosetta Emulation.

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

Set up the installation directory and environment variables

Set up the work directory.

mkdir <directory_name>
cd <directory_name>

For example:

mkdir clientpackage
cd clientpackage

Set the environment variables:

export LH_ROOT_DIR=<path to directory created in step 1(a)>
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

For example:

export LH_ROOT_DIR=/root/ubuntu
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: Use the following table to identify the LH_RELEASE_TAG value:

Table 1. Release tags with Software Hub versions
Software Hub version	Service instance version
5.1.0	`v2.1.0` (`latest`)

The latest tag is set to v2.1.0.

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

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=

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
```

Authenticate with the registry:

$DOCKER_EXE login ${IBM_ICR_IO} \
--username=${PROD_USER} \
--password=${IBM_ENTITLEMENT_KEY}

Run the setup script.

$LH_ROOT_DIR/ibm-lh-client/bin/setup --license_acceptance=y --runtime=$DOCKER_EXE

Installing ibm-lh-client package

Before you begin

Procedure

Installing `ibm-lh-client` package