Use images from GitLab docker repository

[alexxy/gromacs.git] / docs / dev-manual / containers.rst

diff --git a/docs/dev-manual/containers.rst b/docs/dev-manual/containers.rst
index 20cf4d9c25650811dabc0c5bc256c9a87c382d9d..0ca634440c88d964655d7b962b4770f948a0daea 100644 (file)
--- a/docs/dev-manual/containers.rst
+++ b/docs/dev-manual/containers.rst
@@ -9,10 +9,43 @@ A number of images are maintained to provide a breadth of testing coverage.
 Scripts and configuration files for building images are stored in the repository
 under :file:`admin/containers/`
 Images are (re)built manually by |Gromacs| project staff and pushed to
-repositories at https://hub.docker.com/u/gromacs
+DockerHub and GitLab.
+See https://hub.docker.com/u/gromacs and https://gitlab.com/gromacs/gromacs/container_registry
+
+GitLab Container Registry
+=========================
+
+CI Pipelines use a GitLab container registry instead of pulling from Docker Hub.
+
+Project members with role ``Developer`` or higher privilege can
+`push images <https://docs.gitlab.com/ee/user/packages/container_registry/index.html#build-and-push-images-by-using-docker-commands>`__
+to the container registry.
+
+Steps:
+
+1. Create a `personal access token <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`__
+   with ``write_registry`` scope. Save the hash!
+2. Authenticate from the command line with ``docker login registry.gitlab.com -u <token name> -p <hash>``
+3. ``docker push registry.gitlab.com/gromacs/gromacs/<imagename>``
 
 Refer to :file:`buildall.sh` in the ``master`` branch for the set of images
-currently being built.
+currently built.
+
+Within :doc:`pipeline jobs <gitlab>`, jobs specify a Docker image with the *image* property.
+For image naming convention, see :py:func:`utility.image_name`.
+Images from the GitLab registry
+are easily accessible with the same identifier as above.
+For portability, CI environment variables may be preferable for parts of the image identifier.
+Example::
+
+    some_job:
+      image: ${CI_REGISTRY_IMAGE}/ci-<configuration>
+      ...
+
+For more granularity,
+consider equivalent expressions ``${CI_REGISTRY}/${CI_PROJECT_PATH}``
+or ``${CI_REGISTRY}/${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}``
+Ref: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html
 
 Utilities
 =========