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