Add a Docker Image for testing and doc building in an isolated environment (#1075)

PGijsbers · mfeurer · web-flow · commit 97d67e7e2ca8 · 2021-05-07T17:08:23.000+02:00
* Initial structure

* Add doc and test functionality for mounted repo

* Add branch support and safeguards

* Update docker usage and name, add structure

* Improved formatting

* Add reference to docker image from main docs

* Add Workflow to build and push docker image

* Use environment variable directly

* Try other formatting for SHA tag

* Try format as string

* Only push latest

* Explicitly make context relative

* Checkout repository

* Install wheel and setuptools before other packages

* Rename master to main

* Add information about Docker PR

* Make 'note' italtics instead of content

Co-authored-by: Matthias Feurer &lt;feurerm@informatik.uni-freiburg.de&gt;

Co-authored-by: Matthias Feurer &lt;feurerm@informatik.uni-freiburg.de&gt;
diff --git a/.github/workflows/release_docker.yaml b/.github/workflows/release_docker.yaml
@@ -0,0 +1,31 @@
+name: release-docker
+
+on:
+  push:
+    branches:
+      - 'develop'
+      - 'docker'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v1
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+      - name: Login to DockerHub
+        uses: docker/login-action@v1
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - uses: actions/checkout@v2
+      - name: Build and push
+        id: docker_build
+        uses: docker/build-push-action@v2
+        with:
+          context: ./docker/
+          push: true
+          tags: openml/openml-python:latest
+      - name: Image digest
+        run: echo ${{ steps.docker_build.outputs.digest }}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -178,6 +178,10 @@ following rules before you submit a pull request:
  - If any source file is being added to the repository, please add the BSD 3-Clause license to it.
 
 
+*Note*: We recommend to follow the instructions below to install all requirements locally.
+However it is also possible to use the [openml-python docker image](https://github.com/openml/openml-python/blob/main/docker/readme.md) for testing and building documentation.
+This can be useful for one-off contributions or when you are experiencing installation issues.
+
 First install openml with its test dependencies by running
   ```bash
   $ pip install -e .[test]
diff --git a/doc/progress.rst b/doc/progress.rst
@@ -8,7 +8,7 @@ Changelog
 
 0.12.2
 ~~~~~~
-
+* ADD #1075: A docker image is now automatically built on a push to develop. It can be used to build docs or run tests in an isolated environment.
 * DOC: Fixes a few broken links in the documentation.
 * MAINT/DOC: Automatically check for broken external links when building the documentation.
 * MAINT/DOC: Fail documentation building on warnings. This will make the documentation building
diff --git a/doc/usage.rst b/doc/usage.rst
@@ -65,6 +65,19 @@ This file is easily configurable by the ``openml`` command line interface.
 To see where the file is stored, and what its values are, use `openml configure none`.
 Set any field with ``openml configure FIELD`` or even all fields with just ``openml configure``.
 
+~~~~~~
+Docker
+~~~~~~
+
+It is also possible to try out the latest development version of ``openml-python`` with docker:
+
+```
+    docker run -it openml/openml-python
+```
+
+
+See the `openml-python docker documentation <https://github.com/openml/openml-python/blob/main/docker/readme.md>`_ for more information.
+
 ~~~~~~~~~~~~
 Key concepts
 ~~~~~~~~~~~~
diff --git a/docker/Dockerfile b/docker/Dockerfile
@@ -0,0 +1,19 @@
+# Dockerfile to build an image with preinstalled dependencies
+# Useful building docs or running unix tests from a Windows host.
+FROM python:3
+
+RUN git clone  https://github.com/openml/openml-python.git omlp
+WORKDIR omlp
+RUN python -m venv venv
+RUN venv/bin/pip install wheel setuptools
+RUN venv/bin/pip install -e .[test,examples,docs,examples_unix]
+
+WORKDIR /
+RUN mkdir scripts
+ADD startup.sh scripts/
+# Due to the nature of the Docker container it might often be built from Windows.
+# It is typical to have the files with \r\n line-ending, we want to remove it for the unix image.
+RUN sed -i 's/\r//g' scripts/startup.sh
+
+# overwrite the default `python` entrypoint
+ENTRYPOINT ["/bin/bash", "/scripts/startup.sh"]
diff --git a/docker/readme.md b/docker/readme.md
@@ -0,0 +1,86 @@
+# OpenML Python Container
+
+This docker container has the latest development version of openml-python downloaded and pre-installed.
+It can be used to run the unit tests or build the docs in a fresh and/or isolated unix environment.
+Instructions only tested on a Windows host machine.
+
+First pull the docker image:
+
+    docker pull openml/openml-python
+
+## Usage
+
+
+    docker run -it openml/openml-python [DOC,TEST] [BRANCH]
+
+The image is designed to work with two specified directories which may be mounted ([`docker --mount documentation`](https://docs.docker.com/storage/bind-mounts/#start-a-container-with-a-bind-mount)).
+You can mount your openml-python folder to the `/code` directory to run tests or build docs on your local files.
+You can mount an `/output` directory to which the container will write output (currently only used for docs).
+Each can be mounted by adding a `--mount type=bind,source=SOURCE,destination=/DESTINATION` where `SOURCE` is the absolute path to your code or output directory, and `DESTINATION` is either `code` or `output`.
+  
+E.g. mounting a code directory: 
+
+    docker run -i --mount type=bind,source="E:\\repositories/openml-python",destination="/code" -t openml/openml-python
+
+E.g. mounting an output directory: 
+
+    docker run -i --mount type=bind,source="E:\\files/output",destination="/output" -t openml/openml-python
+
+You can mount both at the same time.
+
+### Bash (default)
+By default bash is invoked, you should also use the `-i` flag when starting the container so it processes input: 
+
+    docker run -it openml/openml-python
+
+### Building Documentation
+There are two ways to build documentation, either directly from the `HEAD` of a branch on Github or from your local directory.
+
+#### Building from a local repository
+Building from a local directory requires you to mount it to the ``/code`` directory:
+
+    docker run --mount type=bind,source=PATH_TO_REPOSITORY,destination=/code -t openml/openml-python doc
+
+The produced documentation will be in your repository's ``doc/build`` folder.
+If an `/output` folder is mounted, the documentation will *also* be copied there.
+
+#### Building from an online repository
+Building from a remote repository requires you to specify a branch.
+The branch may be specified by name directly if it exists on the original repository (https://github.com/openml/openml-python/):
+
+    docker run --mount type=bind,source=PATH_TO_OUTPUT,destination=/output -t openml/openml-python doc BRANCH
+
+Where `BRANCH` is the name of the branch for which to generate the documentation.
+It is also possible to build the documentation from the branch on a fork, in this case the `BRANCH` should be specified as `GITHUB_NAME#BRANCH` (e.g. `PGijsbers#my_feature`) and the name of the forked repository should be `openml-python`.
+
+### Running tests
+There are two ways to run tests, either directly from the `HEAD` of a branch on Github or from your local directory.
+It works similar to building docs, but should specify `test` as mode.
+For example, to run tests on your local repository:
+
+    docker run --mount type=bind,source=PATH_TO_REPOSITORY,destination=/code -t openml/openml-python test
+    
+Running tests from the state of an online repository is supported similar to building documentation (i.e. specify `BRANCH` instead of mounting `/code`).
+    
+## Troubleshooting
+
+When you are mounting a directory you can check that it is mounted correctly by running the image in bash mode.
+Navigate to the `/code` and `/output` directories and see if the expected files are there.
+If e.g. there is no code in your mounted `/code`, you should double-check the provided path to your host directory.
+
+## Notes for developers
+This section contains some notes about the structure of the image, intended for those who want to work on it.
+
+### Added Directories
+The `openml/openml-python` image is built on a vanilla `python:3` image.
+Additionally it contains the following files are directories:
+
+ - `/omlp`: contains the openml-python repository in the state with which the image was built by default.
+            If working with a `BRANCH`, this repository will be set to the `HEAD` of `BRANCH`.
+ - `/omlp/venv/`: contains the used virtual environment for `doc` and `test`. It has `openml-python` dependencies pre-installed.
+            When invoked with `doc` or `test`, the dependencies will be updated based on the `setup.py` of the `BRANCH` or mounted `/code`.
+ - `/scripts/startup.sh`: the entrypoint of the image. Takes care of the automated features (e.g. `doc` and `test`).
+
+## Building the image
+To build the image yourself, execute `docker build -f Dockerfile .` from this directory.
+It will use the `startup.sh` as is, so any local changes will be present in the image.
diff --git a/docker/startup.sh b/docker/startup.sh
@@ -0,0 +1,75 @@
+# Entry script to allow docker to be ran for bash, tests and docs.
+# The script assumes a code repository can be mounted to ``/code`` and an output directory to ``/output``.
+# Executes ``mode`` on ``branch`` or the provided ``code`` directory.
+# $1: Mode, optional. Options:
+#        - test: execute unit tests
+#        - doc: build documentation, requires a mounted ``output`` directory if built from a branch.
+#        - if not provided: execute bash.
+# $2: Branch, optional.
+#        Mutually exclusive with mounting a ``code`` directory.
+#        Can be a branch on a Github fork, specified with the USERNAME#BRANCH format.
+#        The test or doc build is executed on this branch.
+
+if [ -z "$1" ]; then
+  echo "Executing in BASH mode."
+  bash
+  exit
+fi
+
+# doc and test modes require mounted directories and/or specified branches
+if ! [ -d "/code" ] && [ -z "$2" ]; then
+  echo "To perform $1 a code repository must be mounted to '/code' or a branch must be specified." >> /dev/stderr
+  exit 1
+fi
+if [ -d "/code" ] && [ -n "$2" ]; then
+  # We want to avoid switching the git environment from within the docker container
+  echo "You can not specify a branch for a mounted code repository." >> /dev/stderr
+  exit 1
+fi
+if [ "$1" == "doc" ]  && [ -n "$2" ] && ! [ -d "/output" ]; then
+    echo "To build docs from an online repository, you need to mount an output directory." >> /dev/stderr
+    exit 1
+fi
+
+if [ -n "$2" ]; then
+  # if a branch is provided, we will pull it into the `omlp` local repository that was created with the image.
+  cd omlp
+  if [[ $2 == *#* ]]; then
+    # If a branch is specified on a fork (with NAME#BRANCH format), we have to construct the url before pulling
+    # We add a trailing '#' delimiter so the second element doesn't get the trailing newline from <<<
+    readarray -d '#' -t fork_name_and_branch<<<"$2#"
+    fork_url="https://github.com/${fork_name_and_branch[0]}/openml-python.git"
+    fork_branch="${fork_name_and_branch[1]}"
+    echo git fetch "$fork_url" "$fork_branch":branch_from_fork
+    git fetch "$fork_url" "$fork_branch":branch_from_fork
+    branch=branch_from_fork
+  else
+    branch=$2
+  fi
+  if ! git checkout "$branch" ; then
+    echo "Could not checkout $branch. If the branch lives on a fork, specify it as USER#BRANCH. Make sure to push the branch." >> /dev/stderr
+    exit 1
+  fi
+  git pull
+  code_dir="/omlp"
+else
+  code_dir="/code"
+fi
+
+source /omlp/venv/bin/activate
+cd $code_dir
+# The most recent ``master`` is already installed, but we want to update any outdated dependencies
+pip install -e .[test,examples,docs,examples_unix]
+
+if [ "$1" == "test" ]; then
+  pytest -n 4 --durations=20 --timeout=600 --timeout-method=thread --dist load -sv
+fi
+
+if [ "$1" == "doc" ]; then
+  cd doc
+  make html
+  make linkcheck
+  if [ -d "/output" ]; then
+    cp -r /omlp/doc/build /output
+  fi
+fi
