Docker provides a way to run applications securely isolated in a container, packaged with all its dependencies and libraries. For a general overview of what Docker is, please see this Wikipedia article. ABB Ability™ History Docker installation can be done by following the instructions under our Running in Docker Tutorial.

There are multiple scenarios where Docker is involved. CpmPlus history on its own is offered as Docker image. There is also concepts such as Edge History and cpmPlus connector which employ Docker containers.

📘

All .NET applications are run with .NET Core in the provided Docker images.

You can pull the image from repository with following command:

docker pull cpmplus-repository.abb.com/cpmplushistory/qa/<platform>

Supported platforms are: x64, x86, aarch64 (64bit armv8), and arm (32bit armv7).

Prepare host

In order to be able to use large databases, the memory map limit parameter must be tuned. A "large" database means anything bigger than few hundred variables development system. The setting must be done in the Docker host computer (it is not possible to execute this in the container itself). The parameter can be changed with the following commands with root privileges:

sysctl -w vm.max_map_count=2147483647
# For non-systemd based systems
echo "vm.max_map_count=2147483647" >> /etc/sysctl.conf
# For systemd based systems
echo "vm.max_map_count=2147483647" >> /etc/sysctl.d/cpmplus.conf

The first command changes the parameter for the running system. The second command makes the parameter persistent across reboots (select one appropriate for your system). After setting this up, if you have any doubt, please reboot the system and check that the value has taken effect with command:

cat /proc/sys/vm/max_map_count

And make sure it returns the same number as we set above (2147483647). If not, you need to figure out how to set this in your system so that it is persisted.

Failing to set this value properly will result in random crashes of the services within the container!

If you use Docker Desktop product in Windows, the above commands must be executed in the DockerDestopVM Hyper-V virtual machine. If Docker uses WSL2 instead of virtual machine to run the host, the command must be executed in the docker-desktop wsl distro. E.g. with commands:

wsl -d docker-desktop
sysctl -w vm.max_map_count=2147483647

The persistent option is not available, according to the current (Aug 2021) information. Instead the command must be executed again after Windows reboots.

Run container

Start the container by giving the container a name, a port number, a path to your RTDB location or a volume name and an image name. Large shared memory is required as well and that should be specified.

docker run --name <your-container-name> --hostname <your-container-name> --shm-size=1T -di -p <your-port>:443 -v <path-to-database-or-volume-name>:/var/lib/rtdbdata <image-name>

Examples

In Linux, with database path

docker run --name cpmplus --hostname cpmplus --shm-size=1T -di -p 443:443 -v /home/data/mydb:/var/lib/rtdbdata cpmplus-repository.abb.com/cpmplushistory/main/x64

... or in Linux, with volume

docker run --name cpmplus --hostname cpmplus --shm-size=1T -di -p 443:443 -v mydb-volume:/var/lib/rtdbdata cpmplus-repository.abb.com/cpmplushistory/main/x64

In Windows, the same path could be, for example C:\data\mydb. Please note that the given RTDB should not be used anywhere else than in the container.

📘

In case of wondering the difference between mapping a path to folder vs. a volume name, check out this article.

Creating a new database when creating the container

You may also give an empty directory as the RTDB location or a non-existing volume. In this case, a new database is created to the given directory or volume when starting the container.

Reading the logs

You can read the NetServer and other logs with:

docker logs <your-container-name>

Configuring Services

In addition to configuring exposed ports and volumes in docker run command, user can give configuration files to the startup scripts. For fluent connectivity it is important to give the server software a certificate and possibly add some certificates for your corporate private key infrastructure. This will allow Vtrin clients such as Vtrin-NetSync in the container to trust servers using the corporate PKI.

You can configure the container by mounting a directory with these files as /config directory to the container. There can currently be 3 different files. These filenames have to be an exact match.

For example put the 3 files in your /home/me/rtdb/config and then run:

docker run --shm-size=1T --name cpmplus -di -p 443:443 -v mydb-volume:/var/lib/rtdbdata -v /home/me/rtdb/config:/config cpmplus-repository.abb.com/cpmplushistory/main/x64

Log in

When the container is successfully running, you may log into https://<your-ip>/history with username: root and password: root from any browser.

Adding packages

If you need more packages you can simply create a new file with the name Dockerfile with the following example content:

FROM cpmplus-repository.abb.com/cpmplushistory/main/x64
RUN apt-get update &&\
        apt-get install -y cpmplushistoryopcuaclient

Then you can build according to this dockerfile with:

docker build -t cpmpluswithopcuaclient .

Run the docker from the new image with example command as follows

docker run --shm-size=1T --name cpmplusuaclient -d -p443:443 -v /home/data/RTDBData:/var/lib/rtdbdata -t cpmpluswithopcuaclient

To enable the service of added package run the below command

docker exec cpmplusuaclient RTDB_OpcUaClient -install /var/lib/rtdbdata

Running Vtrin-Netsync Service

RTDB-Netsync service is not enabled by default. To add the Service entry to RTDB.ini and enable the service,

CSCommon_Cmd -setini /var/lib/rtdbdata/RTDB.INI Services Vtrin-NetSync ON

CSCommon_Cmd -setini /var/lib/rtdbdata/RTDB.INI Vtrin-NetSync BinaryPath "dotnet /usr/share/cpmplus/netcore/Vtrin-NetSync.dll -d"

Known issues

• In case the docker pull <image> fails, use IP instead of the DNS name: replace cpmplus-repository.abb.com with 10.58.44.153.
• Docker for Windows bug: Volume/folder binding might fail after Docker reboot. In case you find connectivity issues with your RTDB container after a reboot, try restarting your RTDB container (docker restart <container-name>). Mounting Windows filesystems to Linux containers is in any case not recommended.
• If you have certificate issues in pulling the image (x509: certificate signed by unknown authority), there are still some certificate configurations to be fixed. Meanwhile, you may add the following insecure registry to the /etc/docker/daemon.json file (different path in Windows) and restart the docker:

{
  "insecure-registries": [
    "https://10.58.44.153",
    "https://cpmplus-repository.abb.com"
  ]
}

• In Windows you can do this with the Docker desktop tool (Settings > Daemon > Insecure registries), where you can add cpmplus-repository.abb.com domain and restart the computer.