Docker Integration¶

Introduction¶

Since htf-1.3 HILSTER supplies multi platform Docker containers for every version that can be used like the htf command line utility. The great advantage is that the user does not need to install and update HILSTER Testing Framework manually because Docker does this job automatically.

For example to download the latest version into Docker simply run

docker pull hilster/htf

Operation Systems¶

HILSTER offers Docker containers for Linux and Windows (both amd64) for the latest supported Python version and every patch release.

This documentation assumes that Windows hosts run Windows Docker containers. It is also possible to run Linux Docker containers from a Windows host. In this case the examples will not work without modification.

Tags¶

HILSTER supports tags for every patch version (e.g. hilster/htf:1.3.1, for every newest minor version (e.g. hilster/htf:1.3) and for every major version (e.g. hilster/htf:1).

The hilster/htf:latest or hilster/htf tags always point to the latest release.

We suggest to use a minor version and not the patch version to be able to automatically update to the newest patch version.

Volumes¶

The Docker containers have one volume to store licences. On Linux the volume is /licenses and on Windows it is C:/licenses. The volumes can also be bind mounted to the host filesystem to persist licenses.

Bind Mounts¶

The following bind mounts /code (Linux) or C:/code (Windows) and /tests (Linux) or C:/tests (Windows) can be used for testing.

code is used to supply user editable code for a project.

tests is used to supply user editable tests. tests is the working directory of the Docker containers.

PYTHONPATH¶

The environment variable PYTHONPATH includes the code and tests volumes so Python will automatically search for modules there.

Activation¶

To activate use the Docker only --activate <activationkey> option, e.g.:

docker run hilster/htf --activate AAAA-BBBB-CCCC-DDDD

The --activate <activationkey> option can also be added to all other options to htf and will be filtered out by a wrapper script that handles the activation. This way it is possible to automatically activate a node for every run for example in a continuous integration system.

Renewal¶

To renew licenses use the Docker only --renew option, e.g.:

docker run hilster/htf --renew

Interactive Mode¶

To run htf in Docker interactively enter

docker run hilster/htf --shell

SSL Verification¶

In some circumstances it might be necessary to disable SSL verification. To do this simply set the environment variable HLM_INSECURE to any value and activate or renew.

docker run -e HLM_INSECURE=1 hilster/htf --activate AAAA-BBBB-CCCC-DDDD

Command Line Utility¶

hilster/htf is used like a command line utility and uses the htf executable as the entry point. So the usage is exactly the same like for the htf command line utility.

Simply replace htf <options> with docker run -it [...] hilster/htf <options>.

You might also like to create an alias for docker run -it [...] hilster/htf named htf to be able to run htf in Docker like they way it would be installed locally.

Community Edition¶

Docker is also available for the community edition. Simply replace the tag htf with htf-community.

docker run hilster/htf-community

Examples¶

Running Tests¶

On Linux run

docker run -it -v $(pwd)/project:/code -v $(pwd)/tests:/tests hilster/htf

and on Windows run

docker run -it -v %cd%/project:C:/code -v %cd%/tests:C:/tests hilster/htf

Running Tests with Activation and persistently stored license¶

Lets assume you have activation key AAAA-BBBB-CCCC-DDDD and the node shall renew its licenses or activate itself.

Linux

Activation:

docker run -it \
    -v $(pwd)/project:/code \
    -v $(pwd)/tests:/tests \
    -v $(pwd)/licenses:/licenses \
    hilster/htf --activate AAAA-BBBB-CCCC-DDDD

Run tests with persistently stored license without activation:

docker run -it \
    -v $(pwd)/project:/code \
    -v $(pwd)/tests:/tests \
    -v $(pwd)/licenses:/licenses \
    hilster/htf

Windows

Activation:

docker run -it ^
    -v %cd%/project:C:/code ^
    -v %cd%/tests:C:/tests ^
    -v %cd%/licenses:C:/licenses ^
    hilster/htf --activate AAAA-BBBB-CCCC-DDDD

Run tests with persistently stored license without activation:

docker run -it ^
    -v %cd%/project:C:/code ^
    -v %cd%/tests:C:/tests ^
    -v %cd%/licenses:C:/licenses ^
    hilster/htf

The --activate <activation key> option is not an htf option but is handled by a wrapper script.

Running Specific Tests¶

Lets assume you have tests.initial_tests as an importable module bind mounted to tests and you only want to run these tests.

On Linux run

docker run -it -v $(pwd)/project:/code -v $(pwd)/tests:/tests hilster/htf initial_tests

and on Windows run

docker run -it -v %cd%/project:C:/code -v %cd%/tests:C:/tests hilster/htf initial_tests

Using Docker for a Project with Dependencies¶

Often you need to add some dependencies for your project stored in requierements.txt. If you need requirements and want to use Docker for testing you can create your own Docker container based on hilster/htf.

To do this create a file requirements.txt with your requirements for example

numpy
matplotlib
scipy

Create a Dockerfile with contents like

FROM hilster/htf
MAINTAINER HILSTER <mail@hilster.io>

ADD requirements.txt requirements.txt
RUN pip install -r requirements.txt

This will add requirements.txt to your container and will install the dependencies while being built.

To build and tag your Docker container simply run

docker build -t <project_name> .

To run your container simply run

docker run -it -v $(pwd)/project:/code -v $(pwd)/tests:/tests <project_name>

on Linux and

docker run -it -v %cd%/project:C:/code -v %cd%/tests:C:/tests <project_name>

on Windows.

Mapping Comports¶

To map a comport on a Linux host use the --device option.

The following example shows how to map /dev/ttyUSB0 to the Docker container.

docker run -it --device=/dev/ttyUSB0 hilster/htf

On Windows devices have a different description in form of <IdType>/><Id>.

The following example maps a comport to the Docker container.

docker run -it --device="class/86E0D1E0-8089-11D0-9CE4-08003E301337" hilster/htf

Mapping USB Dongles¶

On Linux map /sys/bus/usb/devices into the Docker container and use the --privileged option to be able to use USB dongles from within the container.

docker run -it --privileged -v /sys/bus/usb/devices:/sys/bus/usb/devices hilster/htf

On Windows you have to add the corresponding USB device to be handled by the Docker container.