docker comments, version arg

build/Dockerfile

@@ -1,4 +1,10 @@
-FROM  docker.io/library/python:3.7-buster
+# debian buster python3-gpg requires py 3.7 (as of Dec 2020)
+# https://packages.debian.org/buster/python3-gpg
+ARG PY_MAJOR_MINOR_VERSION=3.7
+
+FROM  docker.io/library/python:${PY_MAJOR_MINOR_VERSION}-buster
+
+ARG PY_MAJOR_MINOR_VERSION
 
 WORKDIR /opt/app-root/
 ENV PATH=/opt/app-root/bin:/usr/local/texlive/bin/x86_64-linux:$PATH \
@@ -39,8 +45,10 @@ RUN set -ex \
     && rm -rf /var/lib/apt/lists/* \
     && /usr/local/bin/python -m venv /opt/app-root/ \
     && /opt/app-root/bin/pip install -U pip \
-    && ln -s "/usr/lib/python3/dist-packages/gpg" "/opt/app-root/lib/python3.7/site-packages/" \
-    && ln -s "/usr/lib/python3/dist-packages/gpg-*.egg-info" "/opt/app-root/lib/python3.7/site-packages/" \
+    # apt-get installed python3-gpg to system python, but we want it in /opt/app-root python
+    && ln -s "/usr/lib/python3/dist-packages/gpg" "/opt/app-root/lib/python${PY_MAJOR_MINOR_VERSION}/site-packages/" \
+    && ln -s "/usr/lib/python3/dist-packages/gpg-*.egg-info" "/opt/app-root/lib/python${PY_MAJOR_MINOR_VERSION}/site-packages/" \
+    # ensure python gpg is correctly "installed"
     && /opt/app-root/bin/python -c "import gpg" \
     && groupadd wheel \
     && useradd -M -N -u 1001 -s /bin/bash -g 0 -G wheel user \
@@ -64,10 +72,13 @@ RUN set -ex \
 
 COPY . /tmp/build
 RUN set -ex \
+    # install more tex packages
     && tlmgr --usermode install $(cat /tmp/build/packages.tex) --repository=http://mirrors.ibiblio.org/pub/mirrors/CTAN/systems/texlive/tlnet\
+    # install python packages, finishing with solarforecastarbiter-core[all]
     && /opt/app-root/bin/pip install --no-cache-dir wheel \
     && /opt/app-root/bin/pip install --no-cache-dir -r /tmp/build/requirements.txt -r /tmp/build/requirements-test.txt \
     && /opt/app-root/bin/pip install --no-cache-dir '/tmp/build/.[all]' \
+    # clean up build directory
     && rm -rf /tmp/build \
     && chown -R 1001:0 /opt/app-root
 

build/README.md

@@ -0,0 +1,39 @@
+# Docker image
+
+Docker images are available at [quay.io](https://quay.io/repository/solararbiter/solarforecastarbiter-core)
+
+```
+> docker pull quay.io/solararbiter/solarforecastarbiter-core
+```
+
+Run the image
+
+```
+> docker run --rm quay.io/solararbiter/solarforecastarbiter-core:latest
+Usage: solararbiter [OPTIONS] COMMAND [ARGS]...
+
+  The SolarForecastArbiter core command line tool
+
+Options:
+  --version   Show the version and exit.
+  -h, --help  Show this message and exit.
+
+Commands:
+  fetchnwp             Retrieve weather forecasts with variables relevant
+                       to...
+  referenceaggregates  Updates reference data for the given period.
+  referencedata        Tool for initializing and updating...
+  referencefx          Make reference forecasts
+  referencenwp         Make the reference NWP forecasts that should be...
+  report               Make a report.
+  test                 Test this installation of solarforecastarbiter
+  validate             Run the validation tasks for a given set of...
+```
+
+Build the image from the root directory of the `solarforecastarbiter-core` repository
+
+```
+> docker build -f build/Dockerfile .
+```
+
+See the [Docker documentation](https://docs.docker.com/).