Skip to main content

Operating CODESYS Virtual Control SL with Docker Compose

All products of CODESYS Virtual Control SL can be operated not only with the CODESYS Deploy Tool but also with Docker Compose. The Deploy Tool creates a Compose configuration that you can then use directly with Docker Compose or with graphical tools such as Portainer.

Exporting a Compose file from the Deploy Tool

As of version 4.23.0.0, the CODESYS Deploy Tool can export configured virtual runtimes directly as a Compose file.

To do this, in the Operation tab, in the vPLC section, select the Export → Export to Compose command. This exports all instances with their configuration. You can then use the generated compose.yaml directly with Docker Compose.

Note

The Deploy Tool cannot transfer all settings to the Compose format, in particular the entries in the Generic Commands area. These settings are included as comments in the exported file. Add them manually if necessary.

Assigning network adapters exclusively with nicmapper

nicmapper is a plug-in for Docker that provides direct, exclusive access to a network adapter in a Docker container.

All files for nicmapper are included in the CODESYS Virtual Control SL package. You can find the source code, the installation files, and the sample compose.yaml in the installation directory of CODESYS Development System under CODESYS Virtual Control for Linux SL\Delivery\nicmapper.

Note

The assignment of network interfaces via nicmapper described below is currently supported only for Docker Compose. Podman Compose may require manual adjustments.

When operating via the CODESYS Deploy Tool or the VirtualControlAPI, network adapters are assigned exclusively to a runtime by means of namespacing. This gives the container direct access to the network adapter with the best possible real-time capability.

Docker Compose does not provide native support for this. To enable comparable behavior when using Compose, the nicmapper Docker plug-in is provided.

Installing nicmapper

To install nicmapper, the following requirements must be met on the Linux system:

  • Docker is installed

  • Docker Compose is installed

  • The open-source programming language Go is installed

  • The ip and nsenter commands are available

  • You have root privileges

  1. Copy the nicmapper directory from the installation directory of CODESYS Development System to the Linux system.

  2. On the Linux system, change to the nicmapper directory.

  3. If the build.sh file is in Windows format, convert it to UNIX format.

    dos2unix build.sh

  4. Make the file executable.

    chmod +x build.sh

  5. Run the script.

    sudo ./build.sh

The script installs the plug-in and, optionally, a background service that monitors Docker containers and assigns network interfaces automatically.

For detailed information about installation, uninstallation, and troubleshooting, refer to the included README.md.

Assigning network adapters in the Compose file

Network interfaces are assigned via the cds.nicmapper.nic label. The value corresponds to the format known from the CODESYS Deploy Tool. If you specify multiple network adapters, separate them with commas. The IP address and network mask are optional.

services:
    runtime:
    	image: codesyscontrol_virtuallinux:4.22.0.0
    	container_name: runtime
    	hostname: runtime
        labels:
      		cds.nicmapper.nic: "eth0/10.0.0.5/24,eth1/192.168.32.8/24"

Start the environment in the directory containing the compose.yaml.

docker compose up -d

Note

When the Compose file is created with the Deploy Tool, the cds.nicmapper.nic label is assigned in the correct format.

After startup, nicmapper automatically detects the relevant containers and moves the specified network interfaces into the respective container. This allows products of CODESYS Virtual Control SL to be operated in Compose-based environments as well, with network behavior comparable to a configuration via the CODESYS Deploy Tool. When the container is stopped, nicmapper makes the adapter available to the entire system again.

A complete example of a compose.yaml is included in the package.

In this section: