Install and Use CVB in Docker

Programming Questions
1

Notes:

Starting from version 15.00.000 :cvb: Common Vision Blox installers will be compatible with Docker images. The dependencies and packages prerequisites were reviewed and adopted for a installation within the virtualized environment.

Be aware, that CVBs libraries interact with system and driver related libraries very closely and Docker by design is trying to abstract the application layer away from hardware. It requires a careful treatment with the system, especially when dealing with licensing, acquisition and performance. The only eligible licensing option is passing a dongle into a container.

System Requirements and Prerequisites:

  • Only Linux guests with x64 architecture are currently tested.
  • For licensing, USB Dongles are tested.
  • That is why only Linux hosts are possible, due to the host USB mapping possibility.
  • The host system firewall influences the availability of network devices within containers. So please unblock communication.

Installation

This post is not an introduction into Docker, so please refer to the official pages, for their installation. If you encounter any issue, feel free to reach out to our support team.

Workspace

The following Dockerfile and workspace is a suggestion. For advanced use cases adoptions are required.

TLDR:

Here are two files to build the image directly, create a workspace with two files: Dockerfile and entrypoint.sh, Download CVB and extract in a folder within the workspace called setup. Find a more detailed description below:

Dockerfile 
# Use Ubuntu 24.04 (Noble) as the base image
FROM ubuntu:24.04

# ------------------------------------------------------------------------------
# Environment Variables
# ------------------------------------------------------------------------------

# Set locale and environment variables for CVB (Common Vision Blox)
ENV LANG=C \
    LC_ALL=C \
    CVB=/opt/cvb \
    CVBDATA=/var/opt/cvb \
    CVBCONFIG=/etc/opt/cvb \
    GENICAM_GENTL64_PATH=/opt/cvb/drivers/genicam \
    CVGENICAM_REGISTRY=/var/opt/cvb/Registry \
    DEBIAN_FRONTEND=noninteractive

# ------------------------------------------------------------------------------
# System Dependencies
# ------------------------------------------------------------------------------

# Install required packages for CVB and Python, and trust certificates
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        python3-pip \
        python3-venv \
        libusb-1.0-0 \
        gnupg \
        ca-certificates && \
    rm -rf /var/lib/apt/lists/*  # Clean up to reduce image size

# ------------------------------------------------------------------------------
# Workspace Setup
# ------------------------------------------------------------------------------

# Create workspace directory
RUN mkdir -p /workspace

# Copy CVB setup files into the image
COPY ./setup /workspace/setup

# ------------------------------------------------------------------------------
# Install CVB and Codemeter
# ------------------------------------------------------------------------------

# Set working directory to the setup folder
WORKDIR /workspace/setup

# Install Codemeter runtime package
RUN apt-get update && \
    apt-get install -y --no-install-recommends ./codemeter*.deb

# Install CVB packages (core, tools, dev)
RUN apt-get install -y \
        ./cvb-core*.deb \
        ./cvb-tools-*.deb \
        ./cvb-dev-*.deb

# Clean up apt cache
RUN rm -rf /var/lib/apt/lists/*

# ------------------------------------------------------------------------------
# Python Virtual Environment Setup
# ------------------------------------------------------------------------------

# Create virtual environment for CVBpy and other Python tools
RUN python3 -m venv /opt/venv

# Install CVB Python bindings and dependencies
RUN /opt/venv/bin/pip install /opt/cvb/python/*.whl && \
    /opt/venv/bin/pip install numpy

# ------------------------------------------------------------------------------
# Entrypoint Setup
# ------------------------------------------------------------------------------

# Set working directory
WORKDIR /workspace

# Copy the entrypoint script into the image
COPY ./entrypoint.sh .

# Make the entrypoint script executable
RUN chmod +x entrypoint.sh

# Define container entrypoint
ENTRYPOINT ["/workspace/entrypoint.sh"]
entrypoint.sh 
#!/bin/bash

# Exit immediately if any command fails
set -e

echo "Starting services: cvmgmtd, siGevSvc, and CodemeterLin..."

# Start cvmgmtd service (runs in foreground)
/opt/cvb/bin/cvmgmtd

# Start siGevSvc service in silent mode
/opt/cvb/bin/siGevSvc -s 

# Start CodeMeter license service in the background
/usr/sbin/CodeMeterLin &

# Define the number of license check attempts
MAX_ATTEMPTS=10
FOUND_LICENSE=0

echo "Checking for license availability..."

# Try up to MAX_ATTEMPTS to check if a license is available
for ((i=1; i<=MAX_ATTEMPTS; i++)); do
  # Run embedded Python script to check license status
  result=$(/opt/venv/bin/python3 - <<EOF
import cvb

cvb.wait_for_license(1000)  # Wait up to 1 second for a license

licenses = cvb.get_license_info()
print("FOUND" if licenses else "NOT_FOUND")
EOF
)

  if [ "$result" = "FOUND" ]; then
    FOUND_LICENSE=1
    break
  else
    echo "Attempt $i: No license found, retrying..."
    sleep 1
  fi
done

# Output final result of license check
if [ "$FOUND_LICENSE" = 1 ]; then
    echo "✅ License found."
else
    echo "❌ Could not find a license after $MAX_ATTEMPTS attempts."
fi

# Keep the container running or allow for interactive shell
exec /bin/bash
Download CVB

from here

Detailed guide:

  1. Base Image: As a starting point an official ubuntu Dockerhub hosted image should be used. Include it in your Dockerfile, e.g. with the FROM statement
FROM ubuntu:24.04
  1. Environment: Set CVB specific environment variables for persistency over runs.
ENV LANG=C \
    LC_ALL=C \
    CVB=/opt/cvb \
    CVBDATA=/var/opt/cvb \
    CVBCONFIG=/etc/opt/cvb \
    GENICAM_GENTL64_PATH=/opt/cvb/drivers/genicam \
    CVGENICAM_REGISTRY=/var/opt/cvb/Registry \
    DEBIAN_FRONTEND=noninteractive
  1. Prerequisites: Install prerequisites that are missing within the Ubuntu image compared to the desktop version:
RUN apt-get update && \
    apt-get install -y \
        python3-pip \
        python3-venv \
        libusb-1.0-0 \
        gnupg \
        ca-certificates && \
    rm -rf /var/lib/apt/lists/*  # Clean up to reduce image size

Remarks: Starting from Ubuntu 22, python is a 3rd party application that needs virtual environments in order to not clash with system packages. libusb-1.0.0 is needed for u3v and licensing, gnupg/ca-certificates are system packages for apt.

  1. Installer: Download :cvb: version at least 15.0 for x86_64 Linux from here.
  2. Extraction: Extract the zip alongside your Dockerfile into a folder called setup.
  3. Installation: Copy the folder into your image, install CVB.
RUN apt-get update && \
    apt-get install -y --no-install-recommends ./codemeter*.deb

RUN apt-get install -y \
        ./cvb-core*.deb \
        ./cvb-tools-*.deb \
        ./cvb-dev-*.deb

RUN rm -rf /var/lib/apt/lists/*
  1. Venv and Python Wrapper: Install a python virtual environment and install the cvb python wrapper and numpy.
RUN mkdir -p /opt/venv && python3 -m venv /opt/venv
RUN /opt/venv/bin/pip install /opt/cvb/python/*.whl
RUN /opt/venv/bin/pip install numpy
  1. Entrypoint: Place an entry point script alongside your Dockerfile called entrypoint.sh, with the following contents (starting services on the run and retrieving license):
#!/bin/bash

# Exit immediately if any command fails
set -e

echo "Starting services: cvmgmtd, siGevSvc, and CodemeterLin..."

# Start cvmgmtd service (runs in foreground)
/opt/cvb/bin/cvmgmtd

# Start siGevSvc service in silent mode
/opt/cvb/bin/siGevSvc -s 

# Start CodeMeter license service in the background
/usr/sbin/CodeMeterLin &

# Define the number of license check attempts
MAX_ATTEMPTS=10
FOUND_LICENSE=0

echo "Checking for license availability..."

# Try up to MAX_ATTEMPTS to check if a license is available
for ((i=1; i<=MAX_ATTEMPTS; i++)); do
  # Run embedded Python script to check license status
  result=$(/opt/venv/bin/python3 - <<EOF
import cvb

cvb.wait_for_license(1000)  # Wait up to 1 second for a license

licenses = cvb.get_license_info()
print("FOUND" if licenses else "NOT_FOUND")
EOF
)

  if [ "$result" = "FOUND" ]; then
    FOUND_LICENSE=1
    break
  else
    echo "Attempt $i: No license found, retrying..."
    sleep 1
  fi
done

# Output final result of license check
if [ "$FOUND_LICENSE" = 1 ]; then
    echo "✅ License found."
else
    echo "❌ Could not find a license after $MAX_ATTEMPTS attempts."
fi

# Keep the container running or allow for interactive shell
exec /bin/bash
  1. Concluding defines: Define a working directory, copy the entrypoint script and make docker aware of it:
WORKDIR /workspace
COPY ./entrypoint.sh .
ENTRYPOINT ["/workspace/entrypoint.sh"]
  1. Build: Now build the image by executing the command in a bash within the directory of the Dockerfile.
docker build -t cvb:15.00.000 .
  1. Disable Host Service: If Codemeter is installed on the host system: In order to not block the licensing within the guest, disable the service on the host
sudo systemctl disable codemeter.service
  1. Dongle ID: Find out about the usb bus and device id of the WIBU dongle via the following command on the host:
lsusb

  1. Extract: Sample output:
    image
    The bus id in this example is 001, the device id is 003.

  2. ID Use the information to map this device into the container.
    Remark: Accordingly, U3V cameras can be mapped into the container.

  3. Start Container: Run the container with the bus/device id extracted above. The --network host parameter allows GEV devices connected to the host to be available within the container.

docker run --rm -it --privileged --network host --device /dev/bus/usb/001/003 cvb:15.00.000
  1. Within the container, now a licensed CVB is usable. You should see the following output:

Starting services: cvmgmtd, siGevSvc and CodemeterLin