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.
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.