Skip to content
Browse files

Documentation for the dockers

  • Loading branch information
elpaso committed Nov 20, 2018
1 parent 29875d3 commit a786c40662c476e591401b587c50adfead4c9e98
Showing with 194 additions and 0 deletions.
  1. +194 −0 .docker/
@@ -0,0 +1,194 @@
QGIS Docker images

The QGIS project provides a few official docker images that can be
used for testing purposes.

These dockers are currently used to run continuous integration
tests for the QGIS project itself and to run continuous integration
tests for several third party Python plugins.

The images are automatically built every day and pushed on docker hub
to the QGIS account:

# Available images

## Dependencies image


This is a simple base image that contains all the dependencies required to build
QGIS, it is used by the other images.

Multiple versions of this image may be available: the suffix in the image name indicates the Ubuntu version they are based on.

## Main QGIS image


This is the main image containing a build of QGIS.

### Features

The docker file builds QGIS from the current directory
sets up a testing environment and to run tests inside QGIS.

You can use this docker to test QGIS or to run unit tests inside QGIS,
`xvfb` (A fake X server) is available and running as a service inside the
container to allow for fully automated headless testing in CI pipelines
such as Travis or Circle-CI.

### Building

You can build the image from the main directory of the QGIS source tree with:

$ docker build -t qgis/qgis:latest \
--build-arg DOCKER_TAG=latest \
-f .docker/qgis.dockerfile \

The `DOCKER_TAG` argument, can be used to specify the tag of the dependencies image.

### Running QGIS

You can also use this image to run QGIS on your desktop.

To run a QGIS container, assuming that you want to use your current
display to use QGIS and the image is tagged `qgis/qgis:latest` you can use a script like the one here below:

# Allow connections from any host
$ xhost +
$ docker run --rm -it --name qgis -v /tmp/.X11-unix:/tmp/.X11-unix \
-e DISPLAY=unix$DISPLAY qgis/qgis:latest qgis

This code snippet will launch QGIS inside a container and display the
application on your screen.

### Running unit tests inside QGIS

Suppose that you have local directory containing the tests you want to execute into QGIS:


To run the tests inside the container, you must mount the directory that
contains the tests (e.g. your local directory `/my_tests`) into a volume
that is accessible by the container, see `-v /my_tests/:/tests_directory`
in the example below:

$ docker run -d --name qgis -v /tmp/.X11-unix:/tmp/.X11-unix \
-v /my_tests/:/tests_directory \
-e DISPLAY=:99 \

When done, you can invoke the test runnner by specifying the test
that you want to run, for instance:

$ docker exec -it qgis sh -c "cd /tests_directory && travis_tests.test_TravisTest.run_fail"

The test can be specified by using a dotted notation, similar to Python
import notation, by default the function named `run_all` will be executed
but you can pass another function name as the last item in the dotted syntax:

# Call the default function "run_all" inside test_TravisTest module travis_tests.test_TravisTest
# Call the function "run_fail" inside test_TravisTest module travis_tests.test_TravisTest.run_fail

Please note that in order to make the test script accessible to Python
the calling command must ensure that the tests are in Python path.
Common patterns are:
- change directory to the one containing the tests (like in the examples above)
- add to `PYTHONPATH` the directory contaning the tests

#### Running tests for a Python plugin

All the above considerations applies to this case too, however in order
to simulate the installation of the plugin inside QGIS, you'll need to
make an additional step: call ` <YourPluginName>` in the
docker container before actually running the tests (see the paragraph
about Running on Travis for a complete example).

The `` script prepares QGIS to run in headless mode and
simulate the plugin installation process:

- creates the QGIS profile folders
- installs `` monkey patches to prevent blocking dialogs
- enables the plugin

#### Options for the test runner

The env var `QGIS_EXTRA_OPTIONS` defaults to an empty string and can
contains extra parameters that are passed to QGIS by the test runner.

#### Running on Travis

Here is a simple example for running unit tests of a small QGIS plugin (named *QuickWKT*), assuming that the tests are in `tests/` under
the main directory of the QuickWKT plugin:

- docker
- docker run -d --name qgis-testing-environment -v ${TRAVIS_BUILD_DIR}:/tests_directory -e DISPLAY=:99 qgis/qgis:latest
- sleep 10 # This is required to allow xvfb to start
# Setup qgis and enables the plugin
- docker exec -it qgis-testing-environment sh -c " QuickWKT"
# Additional steps (for example make or paver setup) here
# Link the plugin to the tests_directory
# (this mimicks the plugin download and installation process)
- docker exec -it qgis-testing-environment sh -c "ln -s /tests_directory/ /root/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QuickWKT"
- docker exec -it qgis-testing-environment sh -c "cd /tests_directory && QuickWKT.tests.test_Plugin"

Please note that `cd /tests_directory && ` before the call to `` could be avoided here, because QGIS automatically
adds the plugin main directory to Python path.

#### Implementation notes

The main goal of the test runner in this image is to execute unit tests
inside a real instance of QGIS (not a mocked one).

The QGIS tests should be runnable from a Travis/Circle-CI CI job.

The implementation is:

- run the docker, mounting as volumes the unit tests folder in `/tests_directory`
(or the QGIS plugin folder if the unit tests belong to a plugin and the
plugin is needed to run the tests)
- execute ` MyPluginName` script in docker that sets up QGIS to
avoid blocking modal dialogs and installs the plugin into QGIS if needed
- create config and python plugin folders for QGIS
- enable the plugin in the QGIS configuration file
- install the `` script to disable python exception modal dialogs
- execute the tests by running ` MyPluginName.tests.tests_MyTestModule.run_my_tests_function`
- the output of the tests is captured by the `` script and
searched for `FAILED` (that is in the standard unit tests output) and other
string that indicate a failure or success condition, if a failure condition
is identified, the script exists with `1` otherwise it exits with `0`.

`` accepts a dotted notation path to the test module that
can end with the function that has to be called inside the module to run the
tests. The last part (`.run_my_tests_function`) can be omitted and defaults to

0 comments on commit a786c40

Please sign in to comment.
You can’t perform that action at this time.