Creating the IMS tutorial workspace with Docker Desktop

Use Docker Desktop to create a workspace for the IMS tutorial.

1. Create a project workspace directory.
   At the command prompt on your workstation, change to the directory where you want to create your z/OS Connect API project.

   Note: You can create the project workspace in any directory. For this tutorial, create the project workspace in the Desktop directory if you are using a Mac or the root directory if you are using Windows.
   1. Enter the following command.
      For Windows, enter cd /.
      For MacOS, enter cd ~/Desktop.
   2. Enter the following command to create a project workspace directory called ZCWorkspace.

      mkdir ZCWorkspace

   3. Enter the following command to change to that directory:

      cd ZCWorkspace

   4. In the ZCWorkspace directory, create the subdirectories for the API project. These subdirectories are used for Liberty server configuration files.
      For Windows, enter the following command:

      mkdir PhonebookApi\src\main\liberty\config

      For MacOS, enter the following command:

      mkdir -p PhonebookApi/src/main/liberty/config

   5. In the ZCWorkspace directory, create the logs and certs subdirectories.
      Enter the following commands:

      mkdir logs

      Note: Creating the /certs directory is only required if your connection to IMS uses certificates. This tutorial covers basic authentication. For other security configuration, see Configuring security for IMS connections z/OS Connect zosConnect-3.0.

      mkdir certs

2. Verify that the z/OS Connect Designer image is loaded.
   Run the following command to list the available docker images on your workstation.

   docker image ls

   The following output shows that the z/OS Connect Designer image is now available.

   
   REPOSITORY                                  TAG                             IMAGE ID        CREATED        SIZE
   icr.io/zosconnect/ibm-zcon-designer         3.0.100                          ffba75f49b73    7 hours ago    1.52GB

   Note: The creation timestamp shows when the image itself was first created, not when it was loaded onto your workstation.

3. Create the docker-compose.yaml file.
   Open a new file in your text editor. Copy the contents in Figure 1 and save the file as docker-compose.yaml in the ZCWorkspace directory. Keep the file open in the editor for the next step.

   version: "3.2"
   services:
       zosConnect:
           image: icr.io/zosconnect/ibm-zcon-designer:3.0.100
           environment:
               - IMS_USER=<imsusername>
               - IMS_PASSWORD=<imspassword>
               - IMS_HOST=<imshost>
               - IMS_PORT=<imsport>
               - HTTP_PORT=9080
               - zosconnect_remote_download_allowlist=BLOCK_ALL
           ports:
               - "9443:9443"
               - "9080:9080"
           volumes:
               - ./PhonebookApi:/workspace/project
               - ./logs/:/logs/
               - ./certs:/config/resources/security/:ro
   

4. Add your IMS credentials to the docker-compose.yaml file.
   The file contains the environment array that contains environment variables that can be passed into the container at run time.

   Edit the docker-compose.yaml file as follows.

   1. Replace <imsusername> with your username for connecting to IMS.
   2. Encrypt your password for connecting to IMS.
      Enter the following command, replacing <mypassword> with your own password:

      docker run --rm icr.io/zosconnect/ibm-zcon-designer:3.0.100 securityUtility encode <mypassword> --encoding=aes

      An example of the encrypted password looks something like this:

      {aes}APu1HaGpBzYbH+g8xVbuqUgJPz1ydNS9VbpAq1hsFdGt

      Replace <IMSPassword> in the docker-compose.yaml file with the encrypted password.

   3. Replace <imshost> with your hostname for the IMS region that you are connecting to.
   4. Replace <imsport> with the port number of the IMS region.

   Figure 1 shows the updated docker-compose.yaml file.

   version: "3.2"
   services:
       zosConnect:
           image: icr.io/zosconnect/ibm-zcon-designer:3.0.100
           environment:
               - IMS_USER=username
               - IMS_PASSWORD={aes}APu1HaGpBzYbH+g8xVbuqUgJPz1ydNS9VbpAq1hsFdGt
               - IMS_HOST=myhost
               - IMS_PORT=myport
               - HTTP_PORT=9080
               - zosconnect_remote_download_allowlist=BLOCK_ALL
           ports:
               - "9443:9443"
               - "9080:9080"
           volumes:
               - ./PhonebookApi:/workspace/project
               - ./logs/:/logs/
               - ./certs:/config/resources/security/:ro

   At run time, these environment variables are used to create an IMS connection.

5. Save and close the docker-compose.yaml file.
6. Verify the structure of the files on your workstation in your project workspace directory.
   On the command line, enter dir for Windows or ls for Mac. Verify that the new files and directories are listed correctly. The following screen image shows the expected project structure.

   /ZCWorkspace
   |-- /certs
   |-- /logs
   |-- /PhonebookApi/src/main/liberty/config
   |-- docker-compose.yaml