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 P5 - 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

This guide explains the steps to create a virtual network between two or more Docker containers. This network can be used as the foundation for a redundant or distributed project setup.

This tutorial assumes that you have already set up the container myFirstContainer for your WinCC OA project. This container will act as your first redundancy partner.

Note: It is recommended to have a good understanding of Docker, Docker networking, and WinCC OA before setting up a redundant system in your virtualized container environment.

Using WinCC OA as a virtualized Docker container can be more effective when you create a redundant configuration for your project environment. This guide provides the steps to set up a redundant environment for using WinCC OA in Docker.

  1. Create a new network called myNetwork for 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 named mySecondContainer and connect it to 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 command above must be created using the Dockerfile provided by WinCC OA. Instructions for creating your image file can be found here: Creating a Build Image
  3. Add the existing container myFirstContainer to the network myNetwork. 
    $ docker network connect myNetwork myFirstContainer
    Now, both myFirstContainer and mySecondContainer are part of the same network myNetwork. They can communicate with each other through the Docker network interface.
After completing the steps above, the two Docker containers will share the same virtual network. This allows them to communicate with each other and enables redundancy and distributed options in your Docker environment.

To check if the connection between the containers is working, you can use the following Docker commands:

Ping your Docker container

Use the exec command to send a ping from one Docker container to another:

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

To find the IP address of your Docker container, use the inspect command:

docker inspect