itx-ls Usage example

The following example demonstrates how to import the itx-ls image, how to create a running container and how to execute the example system OneInOneOut.msl. This 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) and whose name matches in*.txt pattern, and for each detected file runs the map OneInOneOut.lnx which reads the file, changes its contents to upper-case, saves a new file to the outputs directory (which must also be created at the same level as the maps, systems and inputs directory) and deletes the source file. The created file has the same name as the input file except the prefix in in it is replaced with the prefix out.

1. Run the following command to load the latest itx-ls docker image archive to the local docker registry:

   docker load -i itx-ls_10.1.2.1.tar.gz

   1. Run the following command to list the images and ensure itx-ls image is imported:

      docker images

      The command returns with the list of images, which includes image with the name itx-ls and the tag 10.1.2.1.
   Note: The 10.1.2.1 tag value assigned to the itx-ls image. It represents the image version and you will use it later to start the container based on this image.
2. 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
3. Optionally you can also create a config directory. You can store dtx.ini 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 localhost/itx-ls:10.1.2.1

   docker cp itx-ls-tmp:/opt/runtime/config /tmp/

   docker rm itx-ls-tmp

   1. Edit /tmp/config/dtx.ini file and customize the settings in it. Refer to the documentation included in the configuration file for details about the individual settings.
      Some of the settings that are commonly custom tuned in dtx.ini configuration file are:
      CooperativeListener=1
      LogInfo=1
      LauncherLog=ewsc
      HeartbeatFileInterval=60
      InitPendingHigh=5000
      InitPendingLow=1000
4. 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 10.1.2 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

5. 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.
6. Run the container by invoking the following command (as one line):

   docker run --name itx-ls -d -w /opt/runtime -v /tmp/config:/opt/runtime/config -v /tmp/itx-ls/data:/data -v /tmp/itx-ls/logs:/logs localhost/itx-ls:10.1.2.1

   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.
7. 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).
8. Run the following commands to perform cleanup, stop and remove the container, remove image, and remove the local directories used as bind mounts:

   docker stop itx-ls

   docker rm itx-ls

   docker rmi localhost/itx-ls:10.1.2.1

   rm -rf /tmp/itx-ls

   rm -rf /tmp/config