Run XESModule for Docker

This scenario serves as an example of how to deploy and start XESModule for Docker inside a Docker container and how to perform basic operations with XEServer running in Docker. The scenario uses the Docker Sample profile hosted in the Edifecs Library.

Prerequisites:

Before you proceed with this section, you must have the following:

  • A 64-bit Linux distribution, if you plan to use Docker on Linux. In this scenario, Ubuntu 16.04 LTS is used in combination with the Docker CE for Ubuntu Docker engine.

    -or-

  • A 64-bit Windows operating system, if you plan to use Docker on Windows. In this scenario, Windows 10 Professional is used in combination with the Docker Desktop Docker engine.
  • An XESModule for Docker image. This is a gzip-compressed .tar archive that contains components and modules required to run an XEServer instance in Docker. To get the XESModule for Docker image, contact Edifecs support.
  • A Smart Trading Cloud Account. The account is required to pull in the XEServer Docker Sample profile from the Smart Trading Cloud Repository.
  • Test EDI data. You can use sample 837 data files from the Docker Sample profile. To do this, download the Docker Sample profile image from Edifecs Library. The image contains two test data files (837P.dat and 837P_Error.dat) at XEServer(9.1.0)_Docker Sample.zip/configuration/config/configuration/testdata/.

Optional

  • A Linux user added to a "docker" group. If you want to run Docker commands as a non-root user, add the user to the docker group.

Run on Linux

To deploy and start XESModule for Docker inside a Docker container:

  1. Open your terminal and load the XESModule for Docker image .tar.gz archive to Docker:

    docker load -i XESDocker_9.2.0.{build}_{date}.tar.gz

    where XESDocker_9.2.0.{build}_{date}.tar.gz is a path to the XESModule for Docker image on the file system.

  2. List all Docker images:

    docker images -a

    This command lists all Docker images. Confirm that the loaded XESModule for Docker image is on the list.

  3. Put your XEServer license file (license.lic) to the directory /host/docker/mount/.

  4. Start the container:

    docker run \
    --name Sample \
    -it \
    -v "/host/docker/mount/license.lic:/opt/Edifecs/XEServer/license.lic" \
    -v "/host/docker/mount/logs:/opt/Edifecs/XEServer/profiles/Docker Sample/log" \
    -v "/host/docker/mount/in:/opt/Edifecs/XEServer/profiles/Docker Sample/workspace/test-data/inbound" \
    -v "/host/docker/mount/out:/opt/Edifecs/XEServer/profiles/Docker Sample/workspace/test-data/outbound" \
    xes:9.2.0.{buildNumber} \
    --image "repository:/library/ProfileImages/Docker/XEServer(9.1.0)_Docker Sample.zip" \
    --username {userName} \
    --password {password}

    where:

    • docker run: Runs the container in an interactive mode.
    • --name Sample: Specifies the name of the container.
    • --it: Instructs Docker to allocate a pseudo-TTY connected to the container’s STDIN.
    • -v "/host/docker/mount/license.lic:/opt/Edifecs/XEServer/license.lic" : Mounts the XEServer license file onto the container.
    • -v "/host/docker/mount/logs:/opt/Edifecs/XEServer/profiles/Docker Sample/log" : Mounts the XEServer logs directory.
    • -v "/host/docker/mount/in:/opt/Edifecs/XEServer/profiles/Docker Sample/workspace/test-data/inbound" : Mounts the XESModule for Docker input directory to submit test data to the container.
    • -v "/host/docker/mount/out:/opt/Edifecs/XEServer/profiles/Docker Sample/workspace/test-data/outbound" : Mounts the XESModule for Docker output directory to view the processing results.
    • xes:9.2.0.{buildNumber} : The reference to the XESModule for Docker image in the format {Repository}:{Tag}.
    • --image "repository:/library/ProfileImages/Docker/XEServer(9.1.0)_Docker Sample.zip" : The link to the sample XEServer profile located at the Edifecs Library. This profile is pulled in from the Edifecs Library when the container starts up.
    • --username {yourUserName} : Your Smart Trading account user name.
    • --password {yourPassword} : Your Smart Trading account password.

    docker run --name Sample \
    -it \
    -v "/host/docker/mount/license.lic:/opt/Edifecs/XEServer/license.lic" \
    -v "/host/docker/mount/logs:/opt/Edifecs/XEServer/profiles/Docker Sample/log" \
    -v "/host/docker/mount/in:/opt/Edifecs/XEServer/profiles/Docker Sample/workspace/test-data/inbound" \
    -v "/host/docker/mount/out:/opt/Edifecs/XEServer/profiles/Docker Sample/workspace/test-data/outbound" \
    -v "/host/docker/XEServer(9.1.0)_Docker Sample.zip:/opt/Edifecs/repository/XEServer(9.1.0)_Docker Sample.zip" \
    xes:9.2.0.{buildNumber}\
    --image "file:/opt/Edifecs/repository/XEServer(9.1.0)_Docker Sample.zip"

  5. List Docker containers:

    docker ps -a

    This command lists all Docker containers. Confirm that the Sample container is running.

  6. Check the XEServer profile status. To do this:

    1. Attach to the container's bash shell:

      docker exec -it $(docker ps -f "name=Sample" -q) /bin/sh

    2. In the container's shell, go to opt/Edifecs/XEServer/bin:

      cd /opt/Edifecs/XEServer/bin

    3. Run the script list_active_profiles.sh to list the active XEServer profiles:

      bash list_active_profiles.sh

  7. Drop the test data files (837P.dat and 837P_Error.dat from the Docker Sample profile image) into the mounted input directory (/host/docker/mount/in). After a short processing delay, the /host/docker/mount/out directory contains files like the following:

    ack_2C3F284F-8934-415C-8E7E-6B250F9132A2-0000003-1-Generate Xdata and Acks_acks.dat
    ack_2C3F284F-8934-415C-8E7E-6B250F9132A2-0000004-2-Generate Xdata and Acks_acks.dat
    ack_6431F27B-F18F-48C9-BD42-2014E05DE502-0000003-1-Generate Xdata and Acks_acks.dat
    ack_6431F27B-F18F-48C9-BD42-2014E05DE502-0000004-2-Generate Xdata and Acks_acks.dat
    ack_AD5F6EA7-C4DB-4D99-91B9-72EF40AA1EA3-0000002-0-Generate Xdata and Acks_acks.dat
    ack_AD5F6EA7-C4DB-4D99-91B9-72EF40AA1EA3-0000003-1-Generate Xdata and Acks_acks.dat
    report_AD5F6EA7-C4DB-4D99-91B9-72EF40AA1EA3-0000001-2-Generate Xdata and Acks_reports.html
    xdata_2C3F284F-8934-415C-8E7E-6B250F9132A2-0000001-0-Generate Xdata and Acks_Xdata.xml

  8. Stop the Docker container:

    docker stop Sample

  9. Remove the Docker container:

    docker rm Sample

Run on Windows

Docker Desktop is a development platform that allows you to set up a Docker environment on your Windows machine. In this section, Docker 19.03.5 version is used. Before you deploy XESModule for Docker into a container, test your Docker installation.

The procedure of running XESModule for Docker in Docker Desktop is identical to the one for Linux, except for the differences that are platform-dependent.

To deploy and start XESModule for Docker on Docker Desktop:

  1. Open your terminal (Command Prompt or PowerShell, but NOT PowerShell ISE) and load the XESModule for Docker .tar.gz image to Docker:

    docker load -i XESDocker_9.2.0.{build}_{date}.tar.gz

    where XESDocker_9.2.0.{build}_{date}.tar.gz is the XESModule for Docker image on your file system. On the first run, Docker Desktop requests you to share the corresponding local drive to access the image file.

  2. List all Docker images:

    docker images -a

    This command lists all the Docker images. Confirm that the uploaded XESModule for Docker image is on the list

  3. Put your XEServer license file (license.lic) to the directory D:\Docker_test\.

  4. Start the container:

    docker run ^
    --name Sample ^
    -it ^
    -v "D:\Docker_test\licence.lic:/opt/Edifecs/XEServer/license.lic" ^
    -v "D:\Docker_test\logs\:/opt/Edifecs/XEServer/profiles/Docker Sample/log/" ^
    -v "D:\Docker_test\in\:/opt/Edifecs/XEServer/profiles/Docker Sample/workspace/test-data/inbound/" ^
    -v "D:\Docker_test\out\:/opt/Edifecs/XEServer/profiles/Docker Sample/workspace/test-data/outbound/" ^
    xes:9.2.0.{buildNumber} ^
    --image "repository:/library/ProfileImages/Docker/XEServer(9.1.0)_Docker Sample.zip" ^
    --username {userName} ^
    --password {password}

    where:

    • docker run: Runs the container in an interactive mode.
    • --name Sample: Specifies the name of the container.
    • --it: Instructs Docker to allocate a pseudo-TTY connected to the container’s STDIN.
    • -v "D:\Docker_test\license.lic:/opt/Edifecs/XEServer/license.lic" : Mounts the XEServer license onto the container.
    • -v "D:\Docker_test\logs:/opt/Edifecs/XEServer/profiles/Docker Sample/log" : Mounts the XEServer logs directory.
    • -v "D:\Docker_test\in:/opt/Edifecs/XEServer/profiles/Docker Sample/workspace/test-data/inbound" : Mounts the XESModule for Docker input directory to submit test data into the container.
    • -v "D:\Docker_test\out:/opt/Edifecs/XEServer/profiles/Docker Sample/workspace/test-data/outbound" : Mounts the XESModule for Docker output directory to view the processing results.
    • xes:9.2.0.{buildNumber} : The reference to the XESModule for Docker image in the format {Repository}:{Tag}.
    • --image "repository:/library/ProfileImages/Docker/XEServer(9.1.0)_Docker Sample.zip" : The link to the sample XEServer profile located at the Edifecs Library. This profile is pulled in from the Edifecs Library when the container starts up.
    • --username {yourUserName} : Your Smart Trading account user name.
    • --password {yourPassword} : Your Smart Trading account password.

  5. List Docker containers:

    docker ps -a

    This command lists all Docker containers. Confirm that the Sample container is running.

  6. Check the XEServer profile status. To do this:

    1. Get the id of the running Docker container and store the id to a temp variable:

      FOR /f %i IN ('docker ps -f "name=Sample" -q') DO SET container_id=%i

    2. Attach to the container's bash shell:

      docker exec -it %container_id% /bin/sh

    3. In the container's shell, go to opt/Edifecs/XEServer/bin:

      cd /opt/Edifecs/XEServer/bin

    4. List active XEServer profiles:

      bash list_active_profiles.sh

      The command returns Docker Sample;10001;1 indicating that the Docker Sample profile that was pulled in from Edifecs Library is up and running.

  7. Drop the test data files (837P.dat and 837P_Error.dat from the Docker Sample profile image) into the mounted input directory (D:\Docker_test\in). After a short processing delay, the D:\Docker_test\out directory contains files like the following:

    ack_2C3F284F-8934-415C-8E7E-6B250F9132A2-0000003-1-Generate Xdata and Acks_acks.dat
    ack_2C3F284F-8934-415C-8E7E-6B250F9132A2-0000004-2-Generate Xdata and Acks_acks.dat
    ack_6431F27B-F18F-48C9-BD42-2014E05DE502-0000003-1-Generate Xdata and Acks_acks.dat
    ack_6431F27B-F18F-48C9-BD42-2014E05DE502-0000004-2-Generate Xdata and Acks_acks.dat
    ack_AD5F6EA7-C4DB-4D99-91B9-72EF40AA1EA3-0000002-0-Generate Xdata and Acks_acks.dat
    ack_AD5F6EA7-C4DB-4D99-91B9-72EF40AA1EA3-0000003-1-Generate Xdata and Acks_acks.dat
    report_AD5F6EA7-C4DB-4D99-91B9-72EF40AA1EA3-0000001-2-Generate Xdata and Acks_reports.html
    xdata_2C3F284F-8934-415C-8E7E-6B250F9132A2-0000001-0-Generate Xdata and Acks_Xdata.xml

  8. Stop the Docker container:

    docker stop Sample

  9. Remove the Docker container:

    docker rm Sample