Document referring to container images by their hash instead of their (…

…#21)

name, as an alternative to the tag system.

Minor updates to asciidoctor-spec image to work with the current REUSE
and update the Node.js version to current (18).

README.md

@@ -25,3 +25,21 @@ In general, any additional arguments are forwarded on to `docker build` except t
 - `./build-all.sh` - Just calls `./build-one.sh` on all the tags listed in it. Use as `./build-all.sh push`
   to push all images to Dockerhub.
   If you add a new Dockerfile to this repo, add it to this script too.
+
+## Container Hashes
+
+We have encountered problems with both gitlab and Github Actions CI not
+flushing cache when an updated image of the same name is pushed to
+dockerhub. While using different tags on every push is a possibility,
+another approach is to use the container SHA256 hash instead of the
+container name. This can be determined at container build time, or as
+follows:
+
+```sh
+$ docker inspect --format='{{index .RepoDigests 0}}' khronosgroup/docker-images:asciidoctor-spec
+khronosgroup/docker-images@sha256:1535246a0270e5a118b11ba121ac3c08849782d27afcac28e3859424db659f2f
+```
+
+Using the last line as the image name in CI will pull that specific hash
+instead of whatever the currently cached version of the underlying image
+name is. This works in both gitlab and Github Actions.

asciidoctor-spec.Dockerfile

@@ -12,7 +12,7 @@ label maintainer="Jon Leech <[email protected]>"
 
 # This adds the Node.js repository to the apt registry
 # nodejs is actually installed in the next step
-run curl -sL https://deb.nodesource.com/setup_12.x | bash -
+run curl -fsSL https://deb.nodesource.com/setup_current.x | bash -
 
 # Debian packages
 # pandoc is for potential use with Markdown
@@ -68,7 +68,10 @@ run gem install -N \
         text-hyphen
 
 # Python packages
-run pip3 install pygments reuse networkx
+# Something odd in the Docker build causes errors if setuptools isn't
+# installed first, although it should be a dependency of the other packages.
+run pip3 install wheel setuptools
+run pip3 install codespell networkx pygments reuse
 
 # JavaScript packages
 # escape-string-regexp is locked @2.0.0 because the current version is an