docs/dev-manual/containers.rst

   1 ==========
   2 Containers
   3 ==========
   4
   5 |Gromacs| project infrastructure uses Docker containerization to
   6 isolate automated tasks.
   7 A number of images are maintained to provide a breadth of testing coverage.
   8
   9 Scripts and configuration files for building images are stored in the repository
  10 under :file:`admin/containers/`
  11 Images are (re)built manually by |Gromacs| project staff and pushed to
  12 DockerHub and GitLab.
  13 See https://hub.docker.com/u/gromacs and https://gitlab.com/gromacs/gromacs/container_registry
  14
  15 GitLab Container Registry
  16 =========================
  17
  18 CI Pipelines use a GitLab container registry instead of pulling from Docker Hub.
  19
  20 Project members with role ``Developer`` or higher privilege can
  21 `push images <https://docs.gitlab.com/ee/user/packages/container_registry/index.html#build-and-push-images-by-using-docker-commands>`__
  22 to the container registry.
  23
  24 Steps:
  25
  26 1. Create a `personal access token <https://gitlab.com/-/profile/personal_access_tokens>`__ (`docs <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`__)
  27    with ``write_registry`` and ``read_registry`` scopes. Save the hash!
  28 2. Authenticate from the command line with ``docker login registry.gitlab.com -u <user name> -p <hash>``
  29 3. ``docker push registry.gitlab.com/gromacs/gromacs/<imagename>``
  30
  31 Refer to :file:`buildall.sh` in the ``master`` branch for the set of images
  32 currently built.
  33
  34 Within :doc:`pipeline jobs <gitlab>`, jobs specify a Docker image with the *image* property.
  35 For image naming convention, see :py:func:`utility.image_name`.
  36 Images from the GitLab registry
  37 are easily accessible with the same identifier as above.
  38 For portability, CI environment variables may be preferable for parts of the image identifier.
  39 Example::
  40
  41     some_job:
  42       image: ${CI_REGISTRY_IMAGE}/ci-<configuration>
  43       ...
  44
  45 For more granularity,
  46 consider equivalent expressions ``${CI_REGISTRY}/${CI_PROJECT_PATH}``
  47 or ``${CI_REGISTRY}/${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}``
  48 Ref: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html
  49
  50 Utilities
  51 =========
  52
  53 :file:`utility.py`
  54 ------------------
  55
  56 .. automodule:: utility
  57     :members:
  58
  59 :file:`scripted_gmx_docker_builds.py`
  60 -------------------------------------
  61
  62 .. automodule:: scripted_gmx_docker_builds