Docker, docs: Document and implement changed image tagging policy

.github/workflows/docker-build.yaml

@@ -34,6 +34,7 @@ jobs:
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{version}}
             type=raw,value=latest,enable={{is_default_branch}}
+            type=raw,value=release,enable=${{ github.ref_type == 'tag' }}
 
       - name: Login to Github Container Registry
         if: github.event_name != 'pull_request'
@@ -52,7 +53,6 @@ jobs:
         with:
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
           platforms: ${{ env.build_platforms }}
 
       - name: Image digest

CHANGES.rst

@@ -22,7 +22,12 @@ New Features
 Breaking Changes
 ^^^^^^^^^^^^^^^^
 
-- TBD
+- Rework the Docker image tagging scheme: ``isso:latest`` is now rebuilt on
+  every push to ``master``, while ``isso:release`` points to the latest stable
+  release (`#970`_, janw). Previously, ``:latest`` pointed to the latest stable
+  (tagged) version
+
+.. _#970: https://github.com/isso-comments/isso/pull/970
 
 Bugfixes & Improvements
 ^^^^^^^^^^^^^^^^^^^^^^^

Dockerfile

@@ -71,6 +71,10 @@ FROM python:3.10-alpine AS isso
 WORKDIR /isso/
 COPY --from=isso-builder /isso/ .
 
+LABEL org.opencontainers.image.source=https://github.com/isso-comments/isso
+LABEL org.opencontainers.image.description="Isso – a commenting server similar to Disqus"
+LABEL org.opencontainers.image.licenses=MIT
+
 # Clean up
 RUN rm -rf /var/apk/cache/* /tmp/* /var/tmp/*
 

Makefile

@@ -38,6 +38,9 @@ APIDOC = npx --no-install apidoc
 
 SASS = sassc
 
+ISSO_IMAGE ?= isso:latest
+ISSO_RELEASE_IMAGE ?= isso:release
+ISSO_DOCKER_REGISTRY ?= ghcr.io/isso-comments
 TESTBED_IMAGE ?= isso-js-testbed:latest
 
 all: js site
@@ -93,21 +96,35 @@ test: $($ISSO_PY_SRC)
 	PYTHONPATH=. pytest --doctest-modules isso/
 
 docker:
-	DOCKER_BUILDKIT=1 docker build -t isso:latest .
+	DOCKER_BUILDKIT=1 docker build -t $(ISSO_IMAGE) .
+
+# For maintainers making releases only:
+docker-release:
+	DOCKER_BUILDKIT=1 docker build -t $(ISSO_IMAGE) .
 
 docker-run:
-	docker run -d --rm --name isso -p 127.0.0.1:8080:8080 --mount type=bind,source=$(PWD)/contrib/isso-dev.cfg,target=/config/isso.cfg,readonly isso:latest isso.run
+	docker run -d --rm --name isso -p 127.0.0.1:8080:8080 \
+		--mount type=bind,source=$(PWD)/contrib/isso-dev.cfg,target=/config/isso.cfg,readonly \
+		$(ISSO_IMAGE) isso.run
 
+# For maintainers only, discouraged in favor of the GitHub action running on
+# every git push
 docker-push:
-	docker tag isso:latest ghcr.io/isso-comments/isso:dev
-	docker push ghcr.io/isso-comments/isso:dev
+	docker tag $(ISSO_IMAGE) $(ISSO_DOCKER_REGISTRY)/$(ISSO_IMAGE)
+	docker push $(ISSO_DOCKER_REGISTRY)/$(ISSO_IMAGE)
+
+# For maintainers making releases only:
+docker-release-push:
+	docker tag $(ISSO_RELEASE_IMAGE) $(ISSO_DOCKER_REGISTRY)/$(ISSO_RELEASE_IMAGE)
+	docker push $(ISSO_DOCKER_REGISTRY)/$(ISSO_RELEASE_IMAGE)
 
 docker-testbed:
-	docker build -f docker/Dockerfile-js-testbed -t isso-js-testbed .
+	docker build -f docker/Dockerfile-js-testbed -t $(TESTBED_IMAGE) .
 
+# For maintainers only:
 docker-testbed-push:
-	docker tag isso-js-testbed:latest ghcr.io/isso-comments/isso-js-testbed:latest
-	docker push ghcr.io/isso-comments/isso-js-testbed:latest
+	docker tag $(TESTBED_IMAGE) $(ISSO_DOCKER_REGISTRY)/$(TESTBED_IMAGE)
+	docker push $(ISSO_DOCKER_REGISTRY)/$(TESTBED_IMAGE)
 
 docker-js-unit:
 	docker run \
@@ -150,4 +167,4 @@ clean:
 	rm -rf .pytest_cache/
 	rm -rf .coverage
 
-.PHONY: apidoc apidoc-init clean coverage docker docker-compare-screenshots docker-generate-screenshots docker-update-screenshots docker-js-unit docker-js-integration docker-push docker-testbed docker-testbed-push init test
+.PHONY: apidoc apidoc-init clean coverage docker docker-compare-screenshots docker-generate-screenshots docker-js-integration docker-js-unit docker-push docker-release docker-release-push docker-run docker-testbed docker-testbed-push docker-update-screenshots init test

README.md

@@ -45,10 +45,20 @@ the [the full documentation](https://isso-comments.de/docs/).
 
 ## Docker
 
-A Docker image with the latest stable release is provided at
-`ghcr.io/isso-comments/isso:latest`. See
+> [!NOTE]  
+> The Docker image tagging scheme for stable releases was changed from `:latest`
+> to `:release` as of March 2024
+> ([#970](https://github.com/isso-comments/isso/pull/970), [#1012](https://github.com/isso-comments/isso/issues/1012))
+
+A [Docker image](https://github.com/isso-comments/isso/pkgs/container/isso) with
+the latest stable release is provided at `ghcr.io/isso-comments/isso:release`,
+while `isso:latest` is rebuilt on every push to the `master` branch. See
 [Using Docker](https://isso-comments.de/docs/reference/installation/#using-docker).
 
+The maintainers recommend pinning the image to a
+[release tag](https://github.com/isso-comments/isso/pkgs/container/isso), e.g.
+`isso:0.13.0`.
+
 ## Contributing
 
 - Pull requests are very much welcome! These might be

docs/docs/reference/installation.rst

@@ -149,12 +149,30 @@ two options for running a Docker container:
 a) Official Docker image
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. attention::
+
+   The Docker image tagging scheme for stable releases was changed from ``:latest``
+   to ``:release`` as of March 2024 (`#970`_, `#1012`_).
+
+.. _#970: https://github.com/isso-comments/isso/pull/970
+.. _#1012: https://github.com/isso-comments/isso/pull/1012
+
+A `Docker image`_ with the latest stable release is provided at
+``ghcr.io/isso-comments/isso:release``, while ``isso:latest`` is rebuilt on
+every push to the ``master`` branch.
+
+The maintainers recommend pinning the image to a `release tag`_, e.g.
+``isso:0.13.0``.
+
 .. code-block:: console
 
-    $ docker pull ghcr.io/isso-comments/isso:latest
+    $ docker pull ghcr.io/isso-comments/isso:release
     $ docker run -d --rm --name isso -p 127.0.0.1:8080:8080 \
         -v /var/lib/isso:/config -v /var/lib/isso:/db \
-        ghcr.io/isso-comments/isso:latest
+        ghcr.io/isso-comments/isso:release
+
+.. _Docker image: https://github.com/isso-comments/isso/pkgs/container/isso
+.. _release tag: https://github.com/isso-comments/isso/pkgs/container/isso
 
 b) Build a Docker image yourself
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^