Skip to main content

Running IBM z/OS in a Docker Container: Step by Step

How to create a ZD&T Docker image and spin a Docker container with the image to run an IBM z/OS system.

01, 02 and 03 in circles to signify a step-by-step process.

In challenging market conditions enterprises are adopting DevOps and cloud to innovate faster and stay ahead of their competition. There is more push to the hybrid cloud than ever before, as enterprises have understood the benefits of cloud. Enterprises have already started their journey to the cloud and are somewhere along the path in their hybrid transformation.

One of the key challenges for organizations on their journey to the cloud, when their new hybrid platform includes the IBM Z® platform, is to ensure that Z developers can adopt the same agile DevOps process as all the other developers on the new platform. Key to this is being able to have multiple development streams, developer flexibility and development insulation from the demands of the mainframe workload. In short it’s about empowering the Z developers to be productive.

IBM is committed to assisting enterprises with their journey to the cloud, and offers assistance in the form of IBM Z Development and Test Environment (ZD&T), a true IBM z/OS® instance that runs on Linux® with the real IBM Z instruction set. It can be deployed on demand and gives developers insulation from peak workloads on the mainframe and prevents them from being impacted by other developers. Testing bottlenecks are removed because teams or developers can have their own test environments created/reset/destroyed whenever they wish without waiting for operations or systems programmers to set up environments for them. With separate insulated development and testing available for IBM Z, true agile development becomes possible for Z. This allows enterprises to have common workflows and process for all their hybrid cloud development.

ZD&T images can be deployed to any OpenStack cloud environment but many organizations use Docker containers in the hybrid cloud world to run workloads. Although there were no obvious technical barriers there was always a question about how easy it would be to run ZD&T in a Docker container. From ZD&T 12.0.4 onwards, IBM introduced updated drivers and now specifically supports running ZD&T in a Docker container (reference link is here). I therefore thought it was an ideal time to see for myself exactly how easy setting up ZD&T in Docker is.

In this article, I’ll describe how I went about creating a ZD&T Docker image and how I spin a Docker container with the image to run an IBM z/OS system. I chose to use the latest release of ZD&T 12.0.5 which emulates IBM z15™ instructions set , but the same process can be used for ZD&T 12.0.4. Only one instance of ZD&T container running z/OS is spun up in the Docker host. Keep in mind that there may be different ways of doing things with Dockers and best practices should be adhered to.

Creating a Docker Image

For this first step, I used Ubuntu 18.04 as my Docker host and Ubuntu as the base image to create ZD&T docker image. In the dockerfile, pre-requisites that are required for ZD&T must be taken care. I added an entry script to the dockerfile,, to take care of things like licenses that can be taken care only after a container has been spun up. My dockerfile looked like this:

From ubuntu
Label Maintainer="Arun Ramachandran"
RUN mkdir /dockertest
COPY ./ZDT_Install_EE_V12.0.5.0.x86_64 /dockertest/
WORKDIR /dockertest
RUN dpkg --add-architecture i386
RUN apt-get -y install apt-utils perl systemd
RUN apt-get -y install libc6:i386 libncurses5:i386 libstdc++6:i386 lib32z1 lib32stdc++6 libasound2
RUN ./ZDT_Install_EE_V12.0.5.0.x86_64  --install --zdtem --dep
CMD /home/ibmsys1/volumes/

Entry Script (

After a ZD&T Docker container has been spun up, it will need the following to function properly:
  • Licenses
  • Unique identification
  • Networking to forward traffic to z/OS
The entry script that I created explicitly installs a gen2 license client and is configured to pick up license from a licenser server using a symbolic variable LM. The symbolic variable, LM will be resolved at run time by assigned value (IP address or DNS) when spinning up a container with docker run command.

Each instance of ZD&T must be uniquely identifiable, and the Unique Identity Manager (UIM) component of license server takes care of this. But, when a Docker container running ZD&T in a Docker host is killed and restarted in the same Docker host, it can create mismatch between the UIM local database and remote database in the server. To address this mismatch, details about the Docker host are removed from the UIM server, using the command, uimreset -r, so that it can be recreated fresh as a part of ZD&T startup.

For forwarding network traffic to z/OS running in the container, just like running ZD&T in a Linux® virtual machine necessary iptables rules can be set up by a shell script and can be invoked as a part of the entry script.
My entry script, looks like this:

echo "Gen2 License client Install"
sleep 5s
echo "Gen2 License client installed"
sleep 5s
echo "Configure Gen2 License client"
/usr/z1090/bin/clientconfig_cli -g2s1 $LM
echo "Gen2 License client configured"
sleep 5s
echo "Reset UIM"
/usr/z1090/bin/uimreset -r
echo "UIM reset"
sleep 5s
echo "Setup iptables"
echo “iptables set”

Persist Changes to IBM z/OS

Typically, changes made to files/directories from a Docker container are lost when the container terminates, unless an option is used to persist changes. To persist changes made to the z/OS system while running in the container, I used bind mounts, where a host directory is shared and mounted to a directory in the container. The contents of this directory are visible to both the Docker host and container. This bind mount is done at run time, when a container is spun up with docker run command.

I created a directory, /dockerzdt, to put all the z/OS volumes, devmap and scripts that the container will require and the Docker container will access it as /home/ibmsys1. To make sure that the container has access to all of the directories and files in /dockerzdt, I had set access permission as rwx (read, write, execute) to all (owner, group and others).

Within the docker container, ZD&T will run under the default user ID, ibmsys1. To set the environment variables required for running ZD&T for ibmsys1 user ID, I added a .bashrc file to the directory, /dockerzdt, which will be available to the ZD&T container as /home/ibmsys1/.bashrc. My .bashrc file looked like this:

export PATH=/usr/z1090/bin:$PATH
export LD_LIBRARY_PATH=/usr/z1090/bin:$LD_LIBRARY_PATH
export MANPATH=/usr/z1090/man:$MANPATH
ulimit -c unlimited
ulimit -d unlimited

Spinning a ZD&T Container

Using the docker run command, we can spin a container from the Docker image. The ZD&T container needs certain ports (1947, 9450, 9451, 3270) for its own purposes and certain ports that z/OS running in it will need like port 23 (TN3270E) and port 2022 (SSHD). I used port mapping to assign ports of Docker host to container, this is done as a part of docker run command using -p option.

The docker run command that I used to spin ZD&T container looked like this:

docker run -it --rm --privileged -p 1947:1947 -p 9450:9450 -p 9451:9451 -p 3270:3270 -p 23:23 -p 2022:2022 --mount type=bind,src=/dockerzdt,dst=/home/ibmsys1 --env LM=17x.x.x.x zdt-docker-image-name

Issuing the above command will spin a container, run the entry script and put us in an interactive mode with the container with a bash shell. Just like a normal Linux machine, one can sudo to ibmsys1 and bring up ZD&T and IPL z/OS either manually or through scripts.

It’s Possible to Run z/OS in a ZD&T Docker Container

It is very much possible to run a z/OS system in a ZD&T Docker container. ZD&T 12.0.4 can bring an IBM z14® environment to a Docker container, whereas ZD&T 12.0.5 can bring an IBM z15 environment to a Docker container. Once a Docker image of ZD&T is created, it can be moved and run wherever needed without needing to install and configure ZD&T, but the z/OS volumes, scripts, and devmap should be made available, so that ZD&T can be brought up and z/OS IPLed.
IBM Systems Webinar Icon

View upcoming and on-demand (IBM Z, IBM i, AIX, Power Systems) webinars.
Register now →