fix: `update-check.sh` should query GH Releases (#3666)

* fix: Source `VERSION` from image ENV

Now CI builds triggered from tagged releases will always have the correct version. No need for manually updating a separate file.

* fix: Query latest GH release tag

Compare to the remote GH release tag published, rather than contents of a `VERSION` file.

`VERSION` file remains in source for now as prior releases still rely on it for an update notification.

* chore: Switch from `yq` to `jaq`

- Can more easily express a string subslice.
- Lighter weight: 9.3M vs 1.7M.
- Drawback, no YAML input/output support.

If `yq` is preferred, the `v` prefix could be removed via BASH easily enough.

* chore: Add entry to `CHANGELOG.md`

* ci: `VERSION` has no relevance to `:edge`

* docs: Update build guide + simplify `make build`

---------

Co-authored-by: Georg Lauterbach <44545919+georglauterbach@users.noreply.github.com>

.github/workflows/default_on_push.yml

@@ -11,7 +11,6 @@ on:
       - .gitmodules
       - Dockerfile
       - setup.sh
-      - VERSION # also update :edge when a release happens
     tags:
       - '*.*.*'
 

.github/workflows/generic_publish.yml

@@ -66,18 +66,13 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: 'Acquire the image version'
-        id: get-version
-        shell: bash
-        run: echo "version=$(<VERSION)" >>"${GITHUB_OUTPUT}"
-
       - name: 'Build and publish images'
         uses: docker/build-push-action@v5.1.0
         with:
           context: .
           build-args: |
+            DMS_RELEASE=${{ github.ref_type == 'tag' && github.ref_name || 'edge' }}
             VCS_REVISION=${{ github.sha }}
-            VCS_VERSION=${{ steps.get-version.outputs.version }}
           platforms: linux/amd64,linux/arm64
           push: true
           tags: ${{ steps.prep.outputs.tags }}

CHANGELOG.md

@@ -12,6 +12,8 @@ This patch release fixes two bugs that Rspamd users encounter on `v13.0.0`. Big
 
 ### Fixed
 
+- **Internal:**
+  - The update check service now queries the latest GH release for a version tag instead of a `VERSION` file from the repo.
 - **Rspamd:**
   - The check for correct permission on the private key when signing e-mails with DKIM was flawed. The result was that a false warning was emitted ([#3669](https://github.com/docker-mailserver/docker-mailserver/pull/3669))
   - When [`RSPAMD_CHECK_AUTHENTICATED=0`][docs::env-rspamd-check-auth], DKIM signing for outbound e-mail was disabled, which is undesirable ([#3669](https://github.com/docker-mailserver/docker-mailserver/pull/3669)). **Make sure to check the documentation of [`RSPAMD_CHECK_AUTHENTICATED`][docs::env-rspamd-check-auth]**!

Dockerfile

@@ -295,8 +295,8 @@ COPY target/scripts/startup/setup.d /usr/local/bin/setup.d
 #
 
 FROM stage-main AS stage-final
+ARG DMS_RELEASE=edge
 ARG VCS_REVISION=unknown
-ARG VCS_VERSION=edge
 
 WORKDIR /
 EXPOSE 25 587 143 465 993 110 995 4190
@@ -327,4 +327,5 @@ LABEL org.opencontainers.image.source="https://github.com/docker-mailserver/dock
 # ARG invalidates cache when it is used by a layer (implicitly affects RUN)
 # Thus to maximize cache, keep these lines last:
 LABEL org.opencontainers.image.revision=${VCS_REVISION}
-LABEL org.opencontainers.image.version=${VCS_VERSION}
+LABEL org.opencontainers.image.version=${DMS_RELEASE}
+ENV DMS_RELEASE=${DMS_RELEASE}

Makefile

@@ -18,11 +18,7 @@ BATS_PARALLEL_JOBS     ?= 2
 all: lint build generate-accounts tests clean
 
 build: ALWAYS_RUN
-	@ DOCKER_BUILDKIT=1 docker build \
-		--tag $(IMAGE_NAME) \
-		--build-arg VCS_VERSION=$(shell git rev-parse --short HEAD) \
-		--build-arg VCS_REVISION=$(shell cat VERSION) \
-		.
+	@ docker build --tag $(IMAGE_NAME) .
 
 generate-accounts: ALWAYS_RUN
 	@ cp test/config/templates/postfix-accounts.cf test/config/postfix-accounts.cf

docs/content/examples/tutorials/docker-build.md

@@ -10,7 +10,7 @@ You'll need to retrieve the git submodules prior to building your own Docker ima
 
 ```sh
 git submodule update --init --recursive
-docker build -t <YOUR CUSTOM IMAGE NAME> .
+docker build --tag <YOUR CUSTOM IMAGE NAME> .
 ```
 
 Or, you can clone and retrieve the submodules in one command:
@@ -21,19 +21,26 @@ git clone --recurse-submodules https://github.com/docker-mailserver/docker-mails
 
 ### About Docker
 
-#### Version
+#### Minimum supported version
 
-We make use of build-features that require a recent version of Docker. Depending on your distribution, please have a look at [the official installation documentation for Docker](https://docs.docker.com/engine/install/) to get the latest version. Otherwise, you may encounter issues, for example with the `--link` flag for a [`#!dockerfile COPY`](https://docs.docker.com/engine/reference/builder/#copy) command.
+We make use of build features that require a recent version of Docker. v23.0 or newer is advised, but earlier releases may work.
 
-#### Environment
+- To get the latest version for your distribution, please have a look at [the official installation documentation for Docker](https://docs.docker.com/engine/install/).
+- If you are using a version of Docker prior to v23.0, you will need to enable BuildKit via the ENV [`DOCKER_BUILDKIT=1`](https://docs.docker.com/build/buildkit/#getting-started).
 
-If you are not using `make` to build the image, note that you will need to provide `DOCKER_BUILDKIT=1` to the `docker build` command for the build to succeed.
+#### Build Arguments (Optional)
 
-#### Build Arguments
+The `Dockerfile` includes several build [`ARG`][docker-docs::builder-arg] instructions that can be configured:
 
-The `Dockerfile` takes additional, so-called build arguments. These are
+- `DOVECOT_COMMUNITY_REPO`: Install Dovecot from the community repo instead of from Debian (default = 1) 
+- `DMS_RELEASE`: The image version (default = edge)
+- `VCS_REVISION`: The git commit hash used for the build (default = unknown)
 
-1. `VCS_VERSION`: the image version (default = edge)
-2. `VCS_REVISION`: the image revision (default = unknown)
+!!! note
 
-When using `make` to build the image, these are filled with proper values. You can build the image without supplying these arguments just fine though.
+    - `DMS_RELEASE` (_when not `edge`_) will be used to check for updates from our GH releases page at runtime due to the default feature [`ENABLE_UPDATE_CHECK=1`][docs::env-update-check].
+    - Both `DMS_RELEASE` and `VCS_REVISION` are also used with `opencontainers` metadata [`LABEL`][docker-docs::builder-label] instructions.
+
+[docs::env-update-check]: https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/#enable_update_check
+[docker-docs::builder-arg]: https://docs.docker.com/engine/reference/builder/#using-arg-variables
+[docker-docs::builder-label]: https://docs.docker.com/engine/reference/builder/#label

target/scripts/build/packages.sh

@@ -205,6 +205,11 @@ function _install_getmail() {
   apt-get "${QUIET}" autoremove
 }
 
+function _install_utils() {
+  _log 'debug' 'Installing utils sourced from Github'
+  curl -sL https://github.com/01mf02/jaq/releases/latest/download/jaq-v1.2.0-x86_64-unknown-linux-musl -o /usr/bin/jaq && chmod +x /usr/bin/jaq
+}
+
 function _remove_data_after_package_installations() {
   _log 'debug' 'Deleting sensitive files (secrets)'
   rm /etc/postsrsd.secret
@@ -228,5 +233,6 @@ _install_dovecot
 _install_rspamd
 _install_fail2ban
 _install_getmail
+_install_utils
 _remove_data_after_package_installations
 _post_installation_steps

target/scripts/start-mailserver.sh

@@ -120,7 +120,7 @@ function _register_functions() {
 
   [[ ${SMTP_ONLY}               -ne 1 ]] && _register_start_daemon '_start_daemon_dovecot'
 
-  [[ ${ENABLE_UPDATE_CHECK}     -eq 1 ]] && _register_start_daemon '_start_daemon_update_check'
+  [[ ${ENABLE_UPDATE_CHECK} -eq 1 ]] && [[ ${DMS_RELEASE} != 'edge' ]] && _register_start_daemon '_start_daemon_update_check'
 
   # The order here matters: Since Rspamd is using Redis, Redis should be started before Rspamd.
   [[ ${ENABLE_RSPAMD_REDIS}     -eq 1 ]] && _register_start_daemon '_start_daemon_rspamd_redis'

target/scripts/update-check.sh

@@ -3,8 +3,8 @@
 # shellcheck source=./helpers/log.sh
 source /usr/local/bin/helpers/log.sh
 
-VERSION=$(</VERSION)
-VERSION_URL='https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/VERSION'
+VERSION="${DMS_RELEASE#v}"
+VERSION_URL='https://github.com/docker-mailserver/docker-mailserver/releases/latest'
 CHANGELOG_URL='https://github.com/docker-mailserver/docker-mailserver/blob/master/CHANGELOG.md'
 
 # check for correct syntax
@@ -17,7 +17,8 @@ fi
 
 while true; do
   # get remote version information
-  LATEST=$(curl -Lsf "${VERSION_URL}")
+  # JSON response provides a field for the release tag, the `v` prefix is removed with `[1:]`
+  LATEST=$(curl -sfL -H 'accept: application/json' "${VERSION_URL}" | jaq -r '.tag_name[1:]')
 
   # did we get a valid response?
   if [[ ${LATEST} =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then