ibm-itx-ls Usage example

About this task

The following example demonstrates how to import the ibm-itx-ls image, create a running container and execute the example OneInOneOut.msl system. The example system watches for new files that appear in the inputs directory (which must be created at the same level as the systems and maps directories). For each file that matches the in*.txt pattern in the inputs directory, the container runs the OneInOneOut.lnx map, which reads the triggering input file, changes the input content to upper-case, saves a new file to the outputs directory (which must also be created at the same level as the inputs directory) and deletes the source file. The created file in the outputs directory has the same name as the input file except the prefix of the file name is changed from in to out.

To import the ibm-itx-ls image, create a running container and execute example system, complete the following steps:

Procedure

Start by logging into the IBM Entitled Registry (cp.icr.io) to pull the ibm-itx-ls image:
```
docker login -u <username> -p <password> cp.icr.io
```
Note: Login credentials, username and password, are provided with the entitlement of the product. Internet access to download the image from the IBM Entitled Registry is a prerequisite for saving the image in the local docker registry or to the local image server.
1. Pull the docker image by image tag or image digest from the IBM Entitled Registry:
```
docker image pull cp.icr.io/cp/ibm-itx-ls:11.0.3.0.20260625
```
```
docker image pull cp.icr.io/cp/ibm-itx-ls@sha256:8e242d20d31d9664eaa7436dffbfdd7b03aedf3312a71d9d45ac1f8a2784ff87
```
  Note: Image tag and digest change when a refreshed container image is published to the IBM Entitled Registry. Replace proper image tag/digest accordingly in the commands listed in this document.
2. If you have downloaded the docker image from the IBM Entitled Registry in a docker archive, for example, ibm-itx-ls_11.0.3.0.20260625.tar.gz, load the ibm-itx-ls docker image archive to the local docker registry:
```
docker load -i ./ibm-itx-ls_11.0.3.0.20260625.tar.gz
```
3. List the images to ensure ibm-itx-ls image was imported:
```
docker images
```
  The command returns the list of images, which includes image with the name ibm-itx-ls and the tag 11.0.3.0.20260625.
Note: The 11.0.3.0.20260625 tag value is assigned to the ibm-itx-ls image. It represents the image version, and you will use it later to start the container. When using docker image pull in step a, the container image name is referenced as cp.icr.io/cp/ibm-itx-ls:11.0.3.0.20260625. When using docker load in step b, the container image name is referenced as localhost/ibm-itx-ls:11.0.3.0.20260625. Please adjust the docker commands below accordingly.
Create directories on the host to serve as bind mounts for the container (Docker managed volumes could be used instead of host managed directories as well). For example, as a test, to create them under /tmp on the host system:
mkdir -p /tmp/itx-ls/logs

mkdir -p /tmp/itx-ls/data/systems

mkdir -p /tmp/itx-ls/data/config

mkdir -p /tmp/itx-ls/data/maps

mkdir -p /tmp/itx-ls/data/tmp

mkdir -p /tmp/itx-ls/data/extra

mkdir -p /tmp/itx-ls/data/mqdata
Optionally you can also create a config directory. You can store config.yaml and other runtime configuration files in it if you wish to modify them from the defaults used by the container. To start with the default configuration files deployed with the image, execute the following commands to create a temporary container and extract the config directory from it to use as a starting point:
```
docker create --name itx-ls-tmp cp.icr.io/cp/ibm-itx-ls:11.0.3.0.20260625
```
```
docker cp itx-ls-tmp:/opt/runtime/config /tmp/
```
```
docker rm itx-ls-tmp
```
1. Edit /tmp/config/config.yaml file and customize the settings in it. Refer to the documentation included in the configuration file for details about the individual settings. The edited copy of the YAML configuration provides individual overrides to the default values within the container. The substance of the overrides can be more clear with few elements in this file. For backward compatibility, the folder may also contain dtx.ini. This feature is deprecated in ITX , but currently it may be used. The INI file becomes the single source of Launcher configuration.
  Some of the settings that are commonly custom tuned in config.yaml configuration file are:
```
runtime:
  m4file:
    FileListenCooperativeListener: true
  launcher:
    InitPendingHigh: 5000
    InitPendingLow: 1000
    HeartbeatFileInterval: 60
    log:
      info: true
    LauncherLog: ewsc
```
  The equivalent but deprecated dtx.ini settings are as follows:
  
  CooperativeListener=1
  
  LogInfo=1
  
  LauncherLog=ewsc
  
  HeartbeatFileInterval=60
  
  InitPendingHigh=5000
  
  InitPendingLow=1000
Save the compiled map OneInOneOut.lnx to /tmp/itx-ls/data/maps directory. This map is a simple transformation map that reads the file in.txt, converts its contents to upper-case text and writes it to file out.txt.
1. Save the compiled system OneInOneOut.msl to /tmp/itx-ls/data/systems directory. This system has OneInOneOut map and has the source card definition overridden to trigger map execution when a file appears at the location that matches expression /data/inputs/in*.txt, write results to /data/outputs/out*.txt file, and delete the source file. The map source file (OneInOneOut.mms) and the system definition file (OneInOneOut.msd) are provided as well, and you can open them in Design Studio 11.0.3 if you wish to modify them or compile them yourself.
2. Run the following commands to copy the compiled map and system files to the maps and systems directories, respectively:
```
cp ./OneInOneOut.lnx /tmp/itx-ls/data/maps
```
```
cp ./OneInOneOut.msl /tmp/itx-ls/data/systems
```
Create the inputs and outputs directories at the same level as the systems and maps directories:
mkdir -p /tmp/itx-ls/data/inputs

mkdir -p /tmp/itx-ls/data/outputs

Note: These locations will correspond to /data/inputs and /data/outputs locations in the container's file system.
Run the container by invoking the following command (as one line):
```
docker run --name itx-ls -e ITX_LS_LICENSE_ACCEPT=true -d -w /opt/runtime -v /tmp/config:/opt/runtime/config -v /tmp/itx-ls/data:/data -v /tmp/itx-ls/logs:/logs cp.icr.io/cp/ibm-itx-ls:11.0.3.0.20260625
```
1. Run the following command to ensure that the itx-ls container is running:
```
docker ps
```
  The command should return a list of running containers, which should include a container with name itx-ls.
Create a file in the /tmp/itx-ls/data/inputs directory as follows:
echo "This is the first test" > /tmp/itx-ls/data/inputs/in1.txt

Note: The created file almost immediately disappears. Check the /tmp/itx-ls/data/outputs directory. It should contain out1.txt file with the content: THIS IS THE FIRST TEST
1. Create another file in the /tmp/itx-ls/data/inputs directory as follows:
  echo "This is another test" > /tmp/itx-ls/data/inputs/in_another.txt
  
  The created file quickly disappears and the file out_another.txt shows up in the /tmp/itx-ls/data/outputs directory with the content: THIS IS ANOTHER TEST
2. Create one more file in the /tmp/itx-ls/data/inputs directory as follows:
  echo "Last test" > /tmp/itx-ls/data/inputs/source.txt
  
  This time the file remains in inputs directory and no new files are created in the outputs directory. This is because the name of the file (source.txt) does not match the expected file name pattern (in*.txt).
Run the following commands to stop the launcher, then remove the container, its image and the bind-mounted directories:
Note: Before running the docker stop command, you may want to pause the Launcher to allow any running maps to shut down gracefully. While the Launcher is automatically paused before a pod is stopped in a distributed Kubernetes deployment, it must be paused manually in a single container setup. Run the following command to manually pause the Launcher:
```
docker exec -e DTX_DATA_DIR=/opt/runtime -it itx-ls bash -c "launcher.sh -pause"
```
```
docker stop itx-ls
```
```
docker rm itx-ls
```
```
docker rmi cp.icr.io/cp/ibm-itx-ls:11.0.3.0.20260625
```
```
rm -rf /tmp/itx-ls
```
```
rm -rf /tmp/config
```