Cleanup docker before 2.3.0b1 release

scripts/Docker/Dockerfile

   Document/implement pip_sdist source mode for testing the source
   distribution. Change from multiple if's to case statement.

   Disable verbose tracing of shells script. Use
   --build-arg="VERBOSE=1" to enable set -xv.

scripts/Docker/roundup_start

   Report error if demo mode is used with 2.2.0. This catches the
   easiest case where build is done using pypi before 2.3.0 final is
   released.

   Indent demo mode PORT_8080 doc block so it's not lost in a wall of
   text.

doc/installation.txt

   Document all source --build-args including how to build from pypi
   using a version specifier. Break out other uses of --build-arg into
   code blocks.

   Reference docker compose section rather than referencing
   docker-compose.yml.

   Clarify docker hub tagging for devel releases.

   Minor formatting fixes.

Author: rouilj

doc/installation.txt

@@ -1641,9 +1641,9 @@ However running cron in a container is problematic (running
 busybox crond as root vs. non-root, requiring setgrp privs
 etc). Patches for implementing email support are welcome.
 
-If you want to use a MySQL backend, the `docker-compose.yml` file will
-deploy a Roundup container and a MySQL container backend for use with
-Roundup.
+If you want to use a MySQL backend, see `Docker-compose 
+Deployment`_ to deploy a Roundup container and a MySQL container
+backend for use with Roundup.
 
 We recommend you follow the `OSWAP Docker Security practices`_ for your
 production Roundup instance.
@@ -1654,24 +1654,65 @@ production Roundup instance.
 Building a Docker Container
 ---------------------------
 
-To build a docker container using the code in the current directory,
-run this build command from the top of the source tree::
+You can build a docker container in one of 4 modes defined by the
+``source`` build-arg.
+
+``--build-arg="source=local"``
+  the default if no source is defined. Build using the version in
+  the source tree by running ``setup.py install``.
+
+``--build-arg="source=pypi"``
+  build the newest production release version deployed to pypi.
+  If you want to build using a pre-release, you can append 
+  `pip version specifiers
+  <https://peps.python.org/pep-0440/#version-specifiers>`_ to
+  `pypi` without embedding any spaces. For example::
+
+     # install 2.2.0 if available or 2.2.0b1 or 2.2.0b2 etc.
+     --build-arg="source=pypi~=2.2.0b1"
+
+     # install only a 2.2.0 beta
+     --build-arg="source=pypi~=2.2.0b1,!=2.2.0"
+
+  Note that versions of Roundup before 2.2 may not run correctly
+  in a Docker container.
+
+``--build-arg="source=pip_local"``
+  Build using the version in the source tree by running ``pip
+  install``. This places some files (e.g. man pages, templates) in
+  different directories from the `local` install but is preferred
+  by some Python users.
+
+``--build-arg="source=pip_sdist"``
+  This is meant for maintainer/developer use. It installs using
+  pip from a source distribution (sdist) tarball built by
+  following the RELEASE.txt. It is meant for testing
+  releases. Normal users/admins should not use it.
+
+Build a docker container using the code in the current directory,
+with this build command from the top of the source tree::
 
      docker build -t roundup-app -f scripts/Docker/Dockerfile .
 
-You can also build a container using the newest Roundup release on
-PyPI, by running::
+Build a container using the newest production (non pre-release)
+Roundup release on PyPI, by running::
 
      docker build -t roundup-app --build-arg="source=pypi" \
           -f scripts/Docker/Dockerfile .
 
-The docker declares a single volume mounted at
-``/usr/src/app/tracker`` inside the container. You will mount your
-tracker home directory at this location. The ``/usr/src/app`` path can
-be changed by using ``--build-arg="appdir=/new/path"``.
+Change the ``build-arg`` for building in other modes.
+
+The Dockerfile declares a single volume mounted at
+``/usr/src/app/tracker`` inside the container. You will mount
+your tracker home directory at this location. The
+``/usr/src/app`` path can be changed by adding::
+
+  --build-arg="appdir=/new/path"
+
+You can also add additional modules to the docker container by
+using::
 
-You can also add additional modules to the docker container by using
-`--build-arg="pip_mod=requests setproctitle"`.
+  --build-arg="pip_mod=requests setproctitle"
 
 Because of deficiencies in the docker program (see:
 https://github.com/moby/moby/issues/29110#issuecomment-1100676306),
@@ -1683,7 +1724,8 @@ suggested ``--build-arg`` to the ``docker build`` command line.
 .. _UID at image build time:
 
 By default the container runs Roundup using UID 1000. By setting
-`--build-arg="roundup_uid=2000"` you can change the UID.
+``--build-arg="roundup_uid=2000"`` you can change the UID and
+GID.
 
 Configuring Roundup in the Container
 ------------------------------------
@@ -1885,9 +1927,10 @@ Tags for Dockerhub Docker Images
 --------------------------------
 
 The docker images available from
-https://hub.docker.com/r/rounduptracker/roundup
-are tagged with: version-build, version, and ``latest`` tags.
-For example, the tags when 2.3.0 is released will be:
+https://hub.docker.com/r/rounduptracker/roundup are tagged with:
+version-build, version, and ``latest`` tags.  Only production
+releases (not pre-releases) are tagged this way. For example, the
+tags when 2.3.0 is released will be:
 
 ``rounduptracker/roundup:latest``
    is a moving tag that tracks the latest build
@@ -1910,11 +1953,12 @@ For example, the tags when 2.3.0 is released will be:
 
 In addition to the release tags, there may be one or more
 development tags available. All tags will start with `devel`. For
-example: ``rounduptracker/roundup:devel``.
+example: ``rounduptracker/roundup:2.3.0b1-devel``,
+``rounduptracker/roundup:devel``
 
-You should not assume that any ``devel`` tag is static. They ae
+You should not assume that any ``devel`` tag is static. They are
 mainly for use by Roundup developer/maintainer for testing. There
-may be alternate tags starting with ``devel-`` to indicate builds
+may be alternate tags ending with ``-devel`` to indicate builds
 from specific Mercurial versions/hashes. Also the tag may be
 overwritten to change the underlying Python libraries or
 images. Unless you like the bleeding edge, these should not be

scripts/Docker/Dockerfile

@@ -10,13 +10,16 @@
 
 
 # Global vars for all build stages
+ARG VERBOSE=
 
 # application directory
 ARG appdir=/usr/src/app
 
 # support roundup install from 'local' directory,
-# 'local_pip' local directory using pip to install or
-# latest release from 'pypi'
+# 'pypi' to install latest final or version specified release
+#   from PyPI,
+# 'pip_local' local directory using pip to install, or
+# 'pip_sdist' to install dist/newest_version-tarball
 ARG source=local
 
 # Python version as a.b Used for installation directory and
@@ -68,7 +71,10 @@ COPY scripts/Docker/sphinxdeps.txt .
 ENV PIP_ROOT_USER_ACTION=ignore
 
 SHELL ["/bin/ash", "-eo", "pipefail", "-c"]
-RUN set -xv && CWD=$PWD && \
+ARG VERBOSE
+
+RUN [ -z "${VERBOSE}" ] || set -xv; \
+    CWD=$PWD && \
     upgrades=$(python3 -m pip --no-cache --disable-pip-version-check \
 	list --outdated | awk 'NR > 2 {print $1}'); \
     if [ -n "$upgrades" ]; then \
@@ -106,25 +112,43 @@ COPY frontends install/frontends/
 COPY locale install/locale/
 COPY roundup install/roundup/
 COPY share install/share/
+# dist is optional so include README.txt so we don't get an error
+COPY README.txt dist/* install/dist/
 
 # verify source has one of two valid values then
 # install in python3 standard directories from local copy
 # or install in python3 standard directories from pypi using pip
 # import from global/command line
 ARG source
-RUN set -xv && if [ "$source" = "local" ] ||  \
-                  [ "$source" = "pypi"  ] || \
-                  [ "$source" = "local_pip"   ]; then :; \
-           else echo "invalid value for source: $source"; \
-                echo "must be local or pypi"; exit 1; fi; \
-    if [ "$source" = "local" ]; then cd install && ./setup.py install; fi; \
-    if [ "$source" = "local_pip" ]; then cd install && \
-               pip -V && \
-               pip install --no-cache-dir . ; \
-    fi; \
-    if [ "$source" = "pypi" ]; then pip install --no-cache-dir roundup; \
-       cp -ril /usr/local/lib/"python${pythonversion}"/site-packages/usr/local/share/* \
-	   /usr/local/share; fi
+
+RUN [ -z "${VERBOSE}" ] || set -xv; \
+    case "$source" in \
+        "local") \
+            cd install && ./setup.py install;; \
+        "pypi"*) \
+            version_spec=$( printf "%s" "$source" | \
+				sed -ne 's/^pypi\([~=!<>].*\)/\1/p'); \
+            pip install --no-cache-dir roundup${version_spec}; \
+            cp -ril /usr/local/lib/"python${pythonversion}"/site-packages/usr/local/share/* \
+               /usr/local/share;; \
+        "pip_local") \
+	    cd install && \
+		pip -V && \
+		pip install --no-cache-dir . ;; \
+	"pip_sdist") \
+	    dist=$(ls install/dist | sed -ne '/roundup-[0-9].*\.tar\.gz$/p' | tail -n 1); \
+	    if [ -z "$dist" ] ; then \
+		printf "Unable to find a source distribution file in dist\n"; \
+		printf "Exiting\n"; \
+		exit 1; \
+            fi; \
+            printf "Building with distribution: %s\n" "$dist"; \
+            pip install --no-cache-dir install/dist/$dist;; \
+        *) \
+            echo "invalid value for source: $source"; \
+	    echo "must be local, pypi, pip_local or pip_sdist"; \
+            exit 1;; \
+    esac
 
 # Allow user to add more modules during build
 ARG pip_mod

scripts/Docker/roundup_start

@@ -34,13 +34,24 @@ for tracker_spec in "$@"; do
 	# if it's a request to start in demo/shell mode:
 	case "$tracker" in
 	    demo)
+		version=$(roundup-admin -v | grep 2.2.0)
+		if [ -n "$version" ]; then
+		    printf "\nRoundup version: %s does not support docker demo mode\n" "$version"
+		    printf "Try building with a version newer than 2.2.0.\n"
+		    printf "For example:\n"
+		    printf " docker build --build-arg=\"source=pypi~=2.3.0a1\" ...\n"
+		    exit 3
+		fi
+
 		if [ -z "$PORT_8080" ]; then
-		    PORT_8080=8917
-		    printf "If docker reports a bind error, you can set the\n"
-		    printf "Docker environment variable PORT_8080 to fix it.\n"
-		    printf "Please add -e PORT_8080=port_number. The\n"
-		    printf "port_number must match the first value to -p \n"
-		    printf "which must be an unused port on your server.\n"
+		  PORT_8080=8917
+		  printf "  If docker reports a bind error, you can set the\n"
+		  printf "  Docker environment variable PORT_8080 to\n"
+		  printf "  fix it.\n\n"
+		  printf "  Add -e PORT_8080=port_number to the docker run\n"
+		  printf "  command. The port_number must match the first\n"
+		  printf "  value to -p which must be an unused port\n"
+		  printf "  on your server.\n\n"
 		fi
 		template=classic
 	        backend=sqlite