python_packaging/docker/README.md

   1 # Docker images
   2
   3 This directory segregates the Dockerfiles to avoid clutter. The Dockerfiles
   4 here help to build and test gmxapi software. They may be subsumed or supplanted
   5 by future Jenkins infrastructure.
   6
   7 Assume you have already checked out the commit you want to build for.
   8 Assume the following definitions.
   9
  10     git fetch https://github.com/gromacs/gromacs.git master
  11     git branch gerrit_master FETCH_HEAD
  12     FORKPOINT=$(git show -s --pretty=format:"%h" `git merge-base gerrit_master HEAD`)
  13     TAG="fr1" # for functional requirement 1
  14
  15 ## Building
  16
  17 Note that the examples show the builds tagged in the `gmxapi` dockerhub namespace.
  18 If you don't have access to it, you can remove `gmxapi/` from the `-t` argument or use
  19 a different dockerhub project space.
  20
  21 The different Dockerfiles require different build contexts (final path argument).
  22
  23 For `gromacs-dependencies`, the build context doesn't matter. Just use `.` in the
  24 `docker` directory.
  25
  26     docker build -t gmxapi/gromacs-dependencies-mpich -f gromacs-dependencies.dockerfile .
  27     # optional:
  28     docker tag gmxapi/gromacs-dependencies-mpich gmxapi/gromacs-dependencies-mpich:${FORKPOINT}
  29
  30 This should rarely be necessary, and the dependent images can probably just pull the `latest`
  31 from dockerhub.
  32
  33 For `gromacs`, the build context needs to be the root of the GROMACS repository (`../..`).
  34 In case images for feature branches diverge too much or become tightly coupled to particular revisions in `master`,
  35 it may be useful to tag this image to annotate the GROMACS build.
  36
  37     # Use DOCKER_CORES to let `make` use all cores available to the Docker engine.
  38     # optionally include an additional `--build-arg REF=${FORKPOINT}`
  39     docker build -t gmxapi/gromacs-mpich --build-arg DOCKER_CORES=4 -f gromacs.dockerfile ../..
  40     # optional:
  41     docker tag gmxapi/gromacs-mpich gmxapi/gromacs-mpich:${FORKPOINT}
  42
  43 For integration testing here, we only want the `python_packaging` subdirectory (`..`).
  44 The image should be tagged according to the functionality it is intended to demonstrate.
  45
  46     docker build -t gmxapi/ci-mpich:${TAG} --build-arg REF=${FORKPOINT} -f ci.dockerfile ..
  47
  48 ## Running
  49
  50 **Warning:** The `--rm` flag tells Docker to remove the container after the
  51 process completes. This prevents unnamed containers from consuming more disk
  52 space on the host with each `run`.
  53
  54 Alternatively, replace `--rm` with `--name containername` to save a named copy
  55 of the container and consider using `commit`ing snapshots of the container.
  56
  57 Refer to Docker documentation for details.
  58
  59 ### ci.dockerfile
  60
  61 The default user for this image is `testing`. The gmxapi and sample_restraint
  62 Python packages are installed into a Python 3 `venv` (virtual environment) owned
  63 by the `testing` user.
  64
  65 The `entrypoint.sh` script activates the python venv and wraps commands in a `bash` `exec`.
  66 The default command is a script sourced from `../scripts/run_pytest.sh`. You can use this,
  67 other scripts, `bash`, etc.
  68
  69     docker run --rm -t gmxapi/ci-mpich:${TAG}
  70     docker run --rm -t gmxapi/ci-mpich:${TAG} run_pytest_mpi
  71     docker run --rm -ti gmxapi/ci-mpich:${TAG} bash
  72
  73 ### Why venv?
  74
  75 `venv` is the suggested and primary installation mode for the gmxapi Python package,
  76 so it is the most important installation mode to test.
  77
  78 These scripts will ultimately be ported to as-yet-undefined GROMACS testing
  79 infrastructure.
  80 It seems equally plausible to have a single image with multiple Python installations
  81 as to have multiple Docker images, or that single-Python docker images would use
  82 some sort of Python virtualenv system to manage non-default Python interpreters.
  83
  84 Since the installation, tests, and shell environment for post-mortem all use the
  85 "testing" user instead of "root", the venv provides a tidy place to work, avoids
  86 the need for the `--user` flag to `pip`, and gives us a convenient place to do
  87 `pip freeze` to get a known baseline of a working Python environment.
  88
  89 #### Entry points
  90
  91 Images have an ENTRYPOINT script that allows
  92 a container to be launched with a reasonable default command, an executable
  93 locatable in the container, or one of the scripts copied from the `scripts`
  94 directory parallel to this one. These additional scripts are primarily to
  95 allow easy execution of certain suites of tests.
  96
  97 See the `scripts` directory for details.
  98
  99 ### Debugging
 100
 101 To be able to step through with gdb, run with something like the following, replacing
 102 'imagename' with the name of the docker image built with this recipe.
 103
 104     docker run --rm -ti --security-opt seccomp=unconfined imagename bash
 105
 106 ### notebook.dockerfile
 107
 108 Built on `gmxapi/ci-mpich:latest`, this image adds a `notebook` entry point to
 109 be used as the new default command. Run with port mapping for http port 8888 for
 110 easy access to a Jupyter notebook server running in the docker container's
 111 `testing` user home directory.
 112
 113     docker run --rm -ti -p 8888:8888 gmxapi/notebook
 114
 115 Note that, when run with `--rm`, changes made to files in the container will be
 116 lost when `docker run` completes.
 117 To preserve work in a notebook run this way,
 118 download the `ipynb` through theJupyter web interface
 119 (such as when updating the examples in the repository).
 120
 121 ### docs.dockerfile
 122
 123 For very quick and isolated documentation builds on top of the gmxapi/ci-mpich
 124 image, build the image from docs .dockerfile.
 125 The resulting image is a small web server image (without GROMACS or gmxapi installed)
 126 with html content built in and copied from a temporary container.
 127
 128     docker run --rm -ti -p 8080:80 gmxapi/docs
 129
 130 Then browse to http://localhost:8080/
 131
 132 ## Automation
 133
 134 *TODO: Update this section as Jenkins infrastructure evolves.*
 135
 136 Travis-CI builds and pushes a chain of Docker images to the `gmxapi` dockerhub organization.
 137 The `kassonlab` GitHub organization `gromacs-gmxapi` repository branches that are descended from the `kassonLabFork`
 138 branch have the necessary Travis-CI configuration.