Remove/replace many mentions of Jenkins

[alexxy/gromacs.git] / python_packaging / docker / README.md

diff --git a/python_packaging/docker/README.md b/python_packaging/docker/README.md
index 73efcc7a4e763e4ed982f70fb76648a0c8b3d5ad..13b7ec7931cceb57a82ec36174dae4ebe63e6464 100644 (file)
--- a/python_packaging/docker/README.md
+++ b/python_packaging/docker/README.md
@@ -2,14 +2,12 @@
 
 This directory segregates the Dockerfiles to avoid clutter. The Dockerfiles
 here help to build and test gmxapi software. They may be subsumed or supplanted
-by future Jenkins infrastructure.
+by future infrastructure.
 
 Assume you have already checked out the commit you want to build for.
 Assume the following definitions.
 
-    git fetch https://github.com/gromacs/gromacs.git master
-    git branch gerrit_master FETCH_HEAD
-    FORKPOINT=$(git show -s --pretty=format:"%h" `git merge-base gerrit_master HEAD`)
+    FORKPOINT=$(git show -s --pretty=format:"%h" `git merge-base master HEAD`)
     TAG="fr1" # for functional requirement 1
 
 ## Building
@@ -58,6 +56,10 @@ Refer to Docker documentation for details.
 
 ### ci.dockerfile
 
+The default user for this image is `testing`. The gmxapi and sample_restraint
+Python packages are installed into a Python 3 `venv` (virtual environment) owned
+by the `testing` user.
+
 The `entrypoint.sh` script activates the python venv and wraps commands in a `bash` `exec`.
 The default command is a script sourced from `../scripts/run_pytest.sh`. You can use this,
 other scripts, `bash`, etc.
@@ -66,6 +68,22 @@ other scripts, `bash`, etc.
     docker run --rm -t gmxapi/ci-mpich:${TAG} run_pytest_mpi
     docker run --rm -ti gmxapi/ci-mpich:${TAG} bash
 
+### Why venv?
+
+`venv` is the suggested and primary installation mode for the gmxapi Python package,
+so it is the most important installation mode to test.
+
+These scripts will ultimately be ported to as-yet-undefined GROMACS testing
+infrastructure.
+It seems equally plausible to have a single image with multiple Python installations
+as to have multiple Docker images, or that single-Python docker images would use
+some sort of Python virtualenv system to manage non-default Python interpreters.
+
+Since the installation, tests, and shell environment for post-mortem all use the
+"testing" user instead of "root", the venv provides a tidy place to work, avoids
+the need for the `--user` flag to `pip`, and gives us a convenient place to do
+`pip freeze` to get a known baseline of a working Python environment.
+
 #### Entry points
 
 Images have an ENTRYPOINT script that allows
@@ -98,9 +116,20 @@ To preserve work in a notebook run this way,
 download the `ipynb` through theJupyter web interface
 (such as when updating the examples in the repository).
 
+### docs.dockerfile
+
+For very quick and isolated documentation builds on top of the gmxapi/ci-mpich 
+image, build the image from docs .dockerfile.
+The resulting image is a small web server image (without GROMACS or gmxapi installed) 
+with html content built in and copied from a temporary container.
+
+    docker run --rm -p 8080:80 gmxapi/docs
+
+Then browse to http://localhost:8080/
+
 ## Automation
 
-*TODO: Update this section as Jenkins infrastructure evolves.*
+*TODO: Update this section as CI infrastructure evolves.*
 
 Travis-CI builds and pushes a chain of Docker images to the `gmxapi` dockerhub organization.
 The `kassonlab` GitHub organization `gromacs-gmxapi` repository branches that are descended from the `kassonLabFork`