Skip to content

Deploying HALCON in Dockerđź”—

When developing or deploying your application using Docker containers on Linux, you need to include the HALCON software in your container image. This section describes how to modify your Dockerfile to install and run HALCON in a Docker container.

To do so, you need to place the following files next to your Dockerfile:

Tip

Have a look at the Docker example under examples/docker/halcon-application of your HALCON installation.

How to include a HALCON installationđź”—

HALCON can be easily installed into a Docker image by adding a command execution line of the offline MVTec Software Installer into the Dockerfile.

Basic HALCON packagesđź”—

Place the installer ZIP file (for example, halcon-26.11.1.0-x64-linux.zip) next to your Dockerfile. You can then use the following line to install the HALCON Runtime package along with the Deep Learning package and the udev rules files, for example:

RUN unzip halcon-26.11.1.0-x64-linux.zip -d /tmp
RUN cd /tmp/halcon-26.11.1.0-x64-linux && \
    ./som install -f halcon-26.11.1 runtime --accept <hash_value> && \
    ./som install -f halcon-26.11.1 deep-learning-thirdparty --accept <hash_value> && \
    ./som install -f halcon-26.11.1 udev-rules --accept <hash_value>

To complete the installation, you need to accept the EULA by adding the specific EULA hash <hash_value> to the installation call. See the SOM documentation for details on how to obtain the hash value and the different installation and package options.

SOM will locate the HALCON installation in the directory /opt/MVTec/Halcon-26.11-Progress-Steady. If your application does not use the rpath linking option to find the HALCON libraries, you may have to add the library path to make sure that the HALCON language interface library is found (see also the corresponding description for your HALCON language interface in Integrating HALCON in applications).

ENV LD_LIBRARY_PATH=/opt/MVTec/Halcon-26.11-Progress-Steady/lib/$HALCONARCH

Required system packagesđź”—

To make sure that all system requirements needed by HALCON are installed, you should also install the according system packages. Use the package manager of the Linux distribution your Docker image is based on. For example, for Ubuntu 22.04, using the apt installation manager, this call could be

RUN apt-get update && apt-get install -y --no-install-recommends \
    libx11-6 \
    libxext6 \
    && rm -rf /var/lib/apt/lists/*

For other versions of Ubuntu or other Linux distributions, the names of the packages may be different. Consult the packages website of your distribution for the correct names.

HALCON language interfaceđź”—

HALCON/C and HALCON/C++ language interfaces already come with the runtime package of a basic HALCON installation and no additional work is necessary.
HALCON/Python and HALCON/.NET interfaces have to be installed with the according package manager of the specific language framework. For example, you install HALCON/Python by using pip

RUN apt-get update && apt-get install -y --no-install-recommends \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

RUN pip install mvtec-halcon==26111 pillow numpy

Use the system package manager to install a package for dotnet-sdk if supported (like apt does for Ubuntu since 22.04). In case support is missing, you can download it from Microsoft. Afterwards, you can install HALCON/.NET using the NuGet package manager for .NET.

RUN apt-get update && apt-get install -y --no-install-recommends \
    wget && \
    wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb \
    -O packages-microsoft-prod.deb && \
    dpkg -i packages-microsoft-prod.deb && \
    rm packages-microsoft-prod.deb && \
    apt-get update && apt-get install -y --no-install-recommends \
    dotnet-sdk-7.0 \
    && apt remove -y wget \
    && rm -rf /var/lib/apt/lists/*

RUN dotnet add package MVTec.HalconDotNet -v 26111

How to include external hardwaređź”—

NVIDIA GPUs for Deep Learningđź”—

Using NVIDIA GPUs requires some additional setup on the host system: The latest graphics driver for the GPU at hand needs to be installed. NVIDIA Container Toolkit needs to be installed to allow Docker access to the GPUs. See the official NVIDIA documentation on installing the NVIDIA Container Toolkit for details.

On an Ubuntu system, the necessary steps are:

  1. Make the package manager aware of the external repository and install the NVIDIA Container Toolkit package.
  2. Configure the Container Toolkit using the nvidia-ctk command.
  3. Restart the Docker daemon.

You can then verify that the setup worked by running nvidia-smi within the container:

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

The flags -runtime=nvidia -gpus=all are required in your Docker run command line for all containers using NVIDIA GPUs.

NVIDIA GPUs for OpenCLđź”—

The host system setup described in the previous subsection is also required here. In addition, you need to install clinfo and verify that your GPU is reported correctly.

Within the image, you need to install some packages for OpenCL and perform a setup to make OpenCL aware of the NVIDIA GPUs:

RUN apt-get update && apt-get install -y --no-install-recommends \
    ocl-icd-libopencl1 \
    opencl-headers \
    clinfo \
    && rm -rf /var/lib/apt/lists/*
RUN mkdir -p /etc/OpenCL/vendors && \
    echo "libnvidia-opencl.so.1" > /etc/OpenCL/vendors/nvidia.icd

How to license HALCON within a Docker containerđź”—

Different licensing options are available for running HALCON in a Docker container:

You can also use an evaluation license. For more information, see Using evaluation licenses.

In any case, you have to copy the license file to the license directory of your HALCON installation in your Docker image. Therefore, add the following line to your Dockerfile:

COPY <license file> /opt/MVTec/Halcon-26.11/license/license.dat

If you intend to reuse the image on different machines, you may want to manage the license separately from the Docker image. In this case, you can optionally bind-mount the license directory as a volume.

How to use a remote dongleđź”—

The use of a remote dongle is explained in Using a license bound to a remote dongle.

  1. As described, you have to modify the license file to add the “Remote Dongle” functionality. Add the additional line
    server=host.docker.internal
    The DNS name resolves to your host system IP address.

    LICENSE MVTec_HALCON 26.11 MODULES=fc123bdomit VALID=2024-11-30 \
            ID=CM:3-3666322 FLAGS=PROGRESS_OK SESSIONS=1 \
            SIGNATURE="519B 0815 E95D C60C 954E \
            06FB 06FB 06FB 06FB 06FB 06FB 06FB DE1D E41F 2037 7637 F86E F55F 8C45 \
            BAC1 5FD4 8408 1CEA 06FB 34E2 36FC 06FB 9DE6 1B01 01BD 7444 DE09" \
            server=host.docker.internal
    
  2. Enable the “Network Server” feature of of the CodeMeter runtime required by the remote dongle feature.

  3. Grant client access to the IP range used by Docker’s network. The IP range of Docker’s default bridge network can be obtained using

    docker network inspect bridge | grep -i subnet
    
  4. When using a Linux host machine you may need to add --add-host=host.docker.internal:host-gateway to your Docker run command to allow Docker to communicate with the host’s network via host.docker.internal.

How to forward a USB license dongle into the container (Linux only)đź”—

This option requires a Linux host system as it is not possible to forward USB devices from Windows hosts into Linux containers.

  1. Prior to interacting with Docker, ensure that hhostid on the host system reports the dongle correctly.

  2. You need the Linux kernel to assign a hidraw device to the dongle for this method to work. To make this happen, ensure that the codemeter service is not running. To deactivate it, use

    sudo systemctl disable --now codemeter.service
    
    Note that for a non-root user in the container a Linux udev rule needs to be set up in the image to enable the access to this host ID.
    RUN mkdir -p /etc/udev/rules.d/
    RUN cp /opt/MVTec/Halcon-26.11/misc/linux/udev/rules.d/59-halcon-codemeter.rules \
        /etc/udev/rules.d/59-halcon-codemeter.rules
    
  3. To grant the container access to the dongle when running the container, forward the corresponding hidraw device. This can be obtained by running the following command after connecting the dongle to the host system, for example:

    grep HID_NAME /sys/class/hidraw/*/device/uevent | grep WIBU
    
  4. To start the container (here: /dev/hidraw4), pass the device, for example:

    docker run --rm -it --runtime=nvidia --gpus=all -v $PWD/src:/home/src \
        --device /dev/hidraw4 <docker_image>