Docker Support

An introduction on how to use WinCC OA within a Docker container, what specifics must be considered and where to find further information on the topic.

What is Docker?

Docker is an open platform for developing, shipping, and running applications. Docker enables you to separate your applications from your infrastructure in order to deliver software quickly. With Docker, you can manage your infrastructure in the same ways you manage your applications. By taking advantage of Docker’s methodologies for shipping, testing, and deploying code quickly, you can significantly reduce the delay between writing code and running it in production. Retrieved from docs.docker.com

More in-depth information on Docker can be found on the official Docker Website.

Tip: Please consider reading the Best Practices for writing Dockerfiles to prevent common issues or unwanted miss-configurations.

WinCC OA and Docker

Starting with V3.18 of WinCC OA, the use of WinCC OA within a Docker container, even for productive usage, is now supported.

Restriction:

The WinCC OA-Video feature cannot be used with Docker, due to the fact that the necessary vimacc components cannot be installed within a container.

Defining a Build Image

To use WinCC OA in Docker, you must create a specific build image.

Predefined Build Image

WinCC OA provides a pre-configured Dockerfile that can be used to create a build image.

The Dockerfile is located in the Debian installation package of WinCC OA. (WinCC OA 3.20 P4 - Debian 11 (Bullseye) - x86_64.zip). The installation can be found at winccoa.com. This file can be used directly and adapted to the specific project requirements.

Within the pre-configured file, the shell script docker-entrypoint.sh is referenced and is used to properly shut-down the WinCC OA PMON as well as the CodeMeter service when stopping the WinCC OA Docker container.

Custom Build Image

To adapt to your specific project requirements, you should familiarize yourself with Docker. The full documentation for creating a custom build image and Docker in general can be found within the official Docker documentation.

Creating a Build Image

To create the configured Docker build image in your Docker environment, call the docker build command, e.g.:

docker build -t winccoa31X .

In the example, it is assumed that the call is made from the folder in which your Dockerfileis located, so the specified PATH is replaced with .. The optional parameter -t winccoa31X is used to add the tag "winccoa31X" to the Docker build.

Additional examples and information on how to run your configured image are described directly in the Dockerfile provided with WinCC OA.

Note: To create a Docker image as a template where no packages are installed directly, the parameter --target noinstall can be added to the docker build call, e.g: 
docker build --target noinstall -t winccoa320temp .

Running the Docker container

Use the docker run command to start a container with the created Docker build image.

You must make sure, that the WinCC OA project is mounted into the correct directory.

By default, the path home/winccoa/oaproj/ is used. To specify a different path, use the optional argument -v of the docker run command.

Use the optional -p argument of the docker run command to map all necessary ports for your project to the Docker container.

For an example of running a container, see

docker run -d --rm --name winccoa -v /home/myuser/myproj:/home/winccoa/oaproj/ -p 4999:4999 -p 5678:5678 -p 8079:8079 winccoa31X

You can also run WinCC OADocker images with a predefined project. To do so, make the following change to the docker-entrypoint.sh script:

$OAPROJEXTRACT - <the path inside the container>

If this path exists, it will be extracted to $OAPROJ, provided that $OAPROJ/config/config does not exist. The project file can be a .tar or a zip file.

The WinCC OA process startup can be delayed with the variable $OASLEEP - if this is defined, it is used as sleep time in seconds, e.g.

$OASLEEP=150

WinCC OA Licensing for Docker

For licensing WinCC OA within a docker container, a stand-alone CodeMeter license server is required.

The CodeMeter license server can either be running on a separate server or as service on the host machine which provides the Docker environment.

A CodeMeter license server requires the installation and corresponding server configuration of the CodeMeter runtime. The runtime is provided as part of the WinCC OA setup or can be downloaded, for Linux only, from winccoa.com or directly from the vendor website wibu.com.

wibu.com also provides extensive descriptions for the configuration of a CodeMeter license server.

Adding a License Server

  • On the central license server web interface under Configuration > Server > Server Access within the area License Access Permission , specify the IP range for clients that are allowed to use licenses.
  • In the docker instance, add the central license server by using the following command: 
    cmu --add-server <server-IP>
  • To check if the server is in the server search list, run the following command: 
    cmu --show-serversearchlist
  • To pass the license server address to a docker container instead of adding it manually, there are two options:
    1. Create and run a docker container with a dedicated license server: 
      docker run -d --rm --name winccoa -v /home/myuser/myproj:/home/winccoa/oaproj/ -p 4999:4999 -p 5678:5678 -p 8079:8079 -e LICENSESERVER=10.0.0.2 winccoa
    2. Start a docker container with the environment variable: 
      VN = LICENSESERVER [, separated if multiple license servers are used]
Note: If the docker loses the connection to the license container, the license will be available again after 30 minutes.

Notes and Restrictions

Please consider following notes and restrictions when using WinCC OA within a Docker container.

  • The usage of WinCC OA within a Docker container is only supported on Linux.
  • A Docker container is not intended to save the configuration, values or history that is created during the runtime. A backup routine must be created and configured to use storage outside of the container. Stopping a container will reset it back to the initial state of the build image!
  • Additional information on how to securely run WinCC OA with Docker are available within the WinCC OA Security Guidelines .
  • The WinCC OA User Interface cannot be run within a Docker Container!
  • Consider the WinCC OA Operating Conditions, especially when using WinCC OA within a virtualized environment like Docker.

Docker - Network

The description below provides you with the necessary steps to create a virtual network between two (or more) Docker container(s) that can be used as the basis for a redundant or distributed project scenario.

The tutorial assumes, that you already configured the container myFirstContainer for your WinCC OA project, containing your first redundancy partner.

Note: Please be aware, that gaining proper knowledge of Docker, Docker networking and WinCC OA in general is advised before setting up a redundant system within your virtualized container environment.

When using WinCC OA as a virtualized docker container it may be beneficial to create a redundant configuration of your project environment. This guide provides you with the necessary steps to create a redundant environment for using WinCC OA in Docker.

  1. Create a new network myNetwork that is used for the communication between the WinCC OA projects. 
    $ docker network create --driver=bridge --subnet=172.28.0.0/16 --ip-range=172.28.5.0/24 --gateway=172.28.5.254 myNetwork
  2. Create a new container mySecondContainer that uses the network myNetwork. 
    $ docker run --name myNewContainer --hostname <HOSTNAME_IHRES_PROJEKTS> --network myNetwork -u <Benutzername>:<Benutzername> -it -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix -v /etc/hosts:/etc/hosts -v /etc/localtime:/etc/localtime:ro <Dockerimage-Name>
    The Docker image file used in the call above must be created using the Dockerfile provided by WinCC OA. A description on how to create your image file can be found in the chapter Docker Support.
  3. Add the existing container to the network myNetwork. 
    $ docker network connect myNetwork myFirstContainer
    Both, the container myFirstContainer as well as the container mySecondContainer, are now part of the same network myNetwork and can establish a connection via the Docker network interface.
After following the steps described above the two Docker container instances will use the same virtual network which enables these containers to communicate with each other and therefore use the redundancy and distributed options within your Docker environment.

To verify if the connection has been successfully established the following docker commands can be used:

Ping your Docker container

To execute a ping command from one Docker container to the other, the exec command can be used:

docker exec -it <Docker image name> ping <IP address of your second container>
Get IP address

To get the IP address of your Docker container, the following inspect command can be used:

docker inspect