Create and edit an IBM z/OS Connect API project with Docker Desktop

Set up an z/OS Connect API project with Docker Desktop.

Before you begin

zosConnect-3.0 Applies to zosConnect-3.0.

Containers Applies to z/OS Connect container deployments.

Ensure that you have:

The IBM® z/OS Connect Designer image available on your development environment.
You have permission to create directories and files in your development environment.

About this task

The task has 2 parts:

Creating the z/OS Connect API project template for the API project development team to use.
Figure 1. Making the API project available in Source Code Management (SCM)
Using the API project template in Docker Desktop.

Figure 2. Using the API project template in Docker Desktop

The example commands in the following procedure use docker. If you are using Podman as your container platform, use podman instead of docker in the example commands.

Procedure

Create a project workspace directory structure.
Note: For this example, the workspace name is apiProjectWorkspace and the API project name is apiProject.

At the command prompt on your workstation, change to the directory where you want to create your z/OS Connect API project and create the following directory structure.
```
/apiProjectWorkspace
|-- /certs
|-- /logs
|-- /apiProject/src/main/liberty/config
```
These directories are mounted into the z/OS Connect Designer container when you start it.
- The /certs directory holds certificates that are needed for connection security to z/OS systems.
- The /logs directory holds logging and messages from your API project that is used for troubleshooting and debugging.
- The /apiProject/src/main/liberty/config directory structure holds any extra server configuration for your API project.
1. Enter the following command to create a project workspace directory called apiProjectWorkspace.
```
mkdir apiProjectWorkspace
```
2. Enter the following command to change to that directory:
```
cd apiProjectWorkspace
```
3. In the apiProjectWorkspace directory, create the subdirectories for the API project. These subdirectories are used for Liberty server configuration files.
  For Windows, enter the following command:
```
mkdir apiProject\src\main\liberty\config
```
  For MacOS, enter the following command:
```
mkdir -p apiProject/src/main/liberty/config
```
  The following image shows the directory structure:
```
/apiProjectWorkspace
|-- /apiProject/src/main/liberty/config
```
4. Place server configuration files into the apiProject/src/main/liberty/config directory.
  This example uses basic authentication, so the server configuration file, db2.xml, is required.
```
<?xml version="1.0" encoding="UTF-8" ?>
<server description="Default server">
    <featureManager>
        <feature>zosconnect:db2-1.0</feature>
    </featureManager>
    <zosconnect_credential user="${DB2_USERNAME}" password="${DB2_PASSWORD}" id="commonCredentials"/>
    <zosconnect_db2Connection id="db2Conn" host="${DB2_HOST}" port="${DB2_PORT}" credentialRef="commonCredentials"/> 
</server>
```
```
/apiProjectWorkspace
|-- /apiProject/src/main/liberty/config/db2.xml
```
  For more information, see Configure IPIC connections to CICS with Docker Desktop and basic authentication, Configuring your connections to Db2, and Configuring connections to IMS with Docker Desktop and basic authentication.
Create a docker-compose.yaml file in the /apiProjectWorkspace directory.
Your API project structure looks like the following structure.
```
/apiProjectWorkspace
|-- /certs
|-- /logs
|-- /apiProject/src/main/liberty/config
|-- docker-compose.yaml
```

Populate the docker-compose.yaml file content.

Modify the following sample configuration if you use a CICS docker-compose.yaml file,

version: "3.2"
services:
    zosConnect:
        image: icr.io/zosconnect/ibm-zcon-designer:3.0.100
        environment:
            - CICS_USER=<cicsUsername>
            - CICS_PASSWORD=<cicsPassword>
            - CICS_HOST=<cicsHost>
            - CICS_PORT=<cicsPort>
            - HTTP_PORT=9080
            - zosconnect_remote_download_allowlist=BLOCK_ALL
        ports:
            - "9443:9443"
            - "9080:9080"
        volumes:
            - ./apiProject:/workspace/project
            - ./logs/:/logs/
            - ./certs:/config/resources/security/:ro

Modify the following sample configuration if you use a Db2 docker-compose.yaml file:

version: "3.2"
services:
    zosConnect:
        image: icr.io/zosconnect/ibm-zcon-designer:3.0.100
        environment:
            - DB2_USERNAME=<db2Username>
            - DB2_PASSWORD=<db2Password>
            - DB2_HOST=<db2Host>
            - DB2_PORT=<db2Port>
            - HTTP_PORT=9080
            - zosconnect_remote_download_allowlist=BLOCK_ALL
        ports:
            - "9443:9443"
            - "9080:9080"
        volumes:
            - ./apiProject:/workspace/project
            - ./logs/:/logs/
            - ./certs:/config/resources/security/:ro

Update the other environment variables in the docker-compose.yaml file.
For more information on updating the environmental variables for your subsystem, see:
Note:
- The environment variables in your docker-compose.yaml depend on which subsystems that you want to connect to from your z/OS Connect API project. You can have environmental variables for more than one subsystem.
- When running with SELinux in enforcing mode on Linux, a bind mount might be required to ensure the correct permissions are set for the mounted file systems. For more information, see Use a bind mount with Docker Compose.
Save the docker-compose.yaml file.
Start the z/OS Connect Designer.
Enter the following command from your z/OS Connect API project workspace:
```
docker compose up -d
```
To stop the z/OS Connect Designer, enter the following command from your z/OS Connect API project workspace:.
```
docker compose down
```

Results

You have successfully created a z/OS Connect API project workspace in Docker Desktop.

Editing an API project

About this task

To edit an existing z/OS Connect API project, update the environment variables, then restart z/OS Connect Designer.

Procedure

Update the docker-compose.yaml environmental variables.

When editing an existing API project from another team or developer, update the docker-compose.yaml file environmental variables with your own credentials.

For example, in figure Figure 3 you might need to update the DB2_USERNAME and DB2_PASSWORD environmental variables.

Figure 3. A sample Db2 API project

version: "3.2"
services:
    zosConnect:
        image: icr.io/zosconnect/ibm-zcon-designer:3.0.100
        environment:
            - DB2_USERNAME=<db2Username>
            - DB2_PASSWORD=<db2Password>
            - DB2_HOST=<db2Host>
            - DB2_PORT=<db2Port>
            - HTTP_PORT=9080
            - zosconnect_remote_download_allowlist=BLOCK_ALL
        ports:
            - "9443:9443"
            - "9080:9080"
        volumes:
            - ./apiProject:/workspace/project
            - ./logs/:/logs/
            - ./certs:/config/resources/security/:ro

Start the z/OS Connect Designer.
Enter the following command in your API project workspace:
```
docker compose up -d
```
To stop the z/OS Connect Designer, enter the following command from your API project workspace:
```
docker compose down
```