Improve image versioning (#114)

* scripts: build: use git to generate human readable versions from upstream * scripts: build: use git description for prind version label * docs: reflect changes in new tagging scheme * docs: add new image versioning scheme to changelog
2025-10-26 07:46:19 +01:00 · 2024-02-22 22:43:56 +01:00
parent ae63c39e7e
commit fbb1c59f97
7 changed files with 51 additions and 35 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ### Added
 ### Fixed
 ### Changed
+- images: all images will now tagged with the [git description](https://git-scm.com/docs/git-describe#_examples) of the upstream repository instead of a shortened SHA in an attempt to make image versions easier to understand (numbers always go up :rocket:) via #114 and #111
+- docs: reflect new tagging scheme
 ### Removed
+**Full Changelog**: https://github.com/mkuf/prind/compare/vX.X.X...vX.X.X
 -->

 ## [v1.10.0] - 2024-02-08
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ Currently supported Frontends:
 Depending on which Frontend you've chosen, moonraker will also be deployed.

 ## Getting started
-The following Guide requires ``docker`` and ``docker compose`` on your machine.  
+The following Guide requires `docker`` and ``docker compose` on your machine.  
 Follow the official Guides on how to get them up and running. 
 * https://docs.docker.com/engine/install/ubuntu/
 * https://docs.docker.com/compose/cli-command/#installing-compose-v2
@@ -39,8 +39,8 @@ make flash FLASH_DEVICE=/dev/serial/by-id/<my printer>
 If your Board can be flashed via SD-Card, you may want to omit `make flash` and retrieve the `klipper.bin` from the `out` directory that is created by `make`. Follow your boards instructions on how to proceed with flashing via SD-Card.

 ### Add your Configuration to docker-compose.override.yaml
-Locate the ``webcam`` Service within ``docker-compose.override.yaml`` and update the ``device`` Section with the Device Name of your Webcam.  
-In this example, the Webcam is using device ``/dev/video0``. Do not edit any other lines.
+Locate the `webcam`` Service within ``docker-compose.override.yaml`` and update the ``device` Section with the Device Name of your Webcam.  
+In this example, the Webcam is using device `/dev/video0`. Do not edit any other lines.
 ```yaml
  webcam:
    <<: *ustreamer-svc
@@ -56,9 +56,9 @@ In this example, the Webcam is using device ``/dev/video0``. Do not edit any oth
 ```

 ### Configuring Klipper/Moonraker
-All Runtime Configs are stored within ``config`` of this Repo.  
-* Update ``config/printer.cfg`` with your Klipper config, set the serial device and make sure to not remove the existing Macros as they are required by fluidd/mainsail. See [Klipper3d Docs](https://www.klipper3d.org/Config_Reference.html) for Reference
-* Make sure to update ``cors_domains`` and ``trusted_clients`` within ``moonraker.cfg`` to secure your moonraker api from unwanted access. See [Moonraker Docs](https://moonraker.readthedocs.io/en/latest/configuration/) for Reference
+All Runtime Configs are stored within `config` of this Repo.  
+* Update `config/printer.cfg` with your Klipper config, set the serial device and make sure to not remove the existing Macros as they are required by fluidd/mainsail. See [Klipper3d Docs](https://www.klipper3d.org/Config_Reference.html) for Reference
+* Make sure to update `cors_domains`` and ``trusted_clients`` within ``moonraker.cfg` to secure your moonraker api from unwanted access. See [Moonraker Docs](https://moonraker.readthedocs.io/en/latest/configuration/) for Reference

 ### Starting the stack
 There are currently 3 frontend Profiles to choose from, depending on the Web Frontend you'd like to use.
@@ -181,14 +181,14 @@ docker compose --profile mainsail --profile moonraker-obico up -d


 ## Updating
-Images are built daily and tagged with latest and the first seven chars of the commit-sha of the remote repo. 
+Images are built daily and tagged with `latest` and the [git description](https://git-scm.com/docs/git-describe#_examples) of the remote repo. 
 Example: 

-* ``mkuf/klipper:latest``
-* ``mkuf/klipper:a33d069``
+* `mkuf/klipper:latest`
+* `mkuf/klipper:v0.12.0-114-ga77d0790`

-The ``latest`` Tag will point to a new Image within 24h.  
-The SHA-Tag ``a33d069`` will remain and refers to [Klipper3d/klipper:a33d069](https://github.com/Klipper3d/klipper/commit/a33d0697b6438e362f0cf9d25e1e8358d331bf53)
+The `latest` Tag will point to a new Image within 24h.  
+The descriptive Tag `v0.12.0-114-ga77d0790` will remain and refers to [Klipper3d/klipper:v0.12.0-114-ga77d0790](https://github.com/Klipper3d/klipper/commit/a77d07907fdfcd76f7175231caee170db205ff04)

 Updating can be handled via docker-compose.  
 docker-compose.yaml uses latest tags for all Images contained in this Repository.  
@@ -272,7 +272,7 @@ Example from service Klipper:

 ### Multiple Webcams
 The Ustreamer Service is already templated to be easily reused for multi-webcam Setups.  
-To add a new Ustreamer Service, simply add the following snippet to ``docker-compose.override.yaml``.  
+To add a new Ustreamer Service, simply add the following snippet to `docker-compose.override.yaml`.  
 Notice, that all service names, container names and traefik labels need to be unique while the right side of the passed Device (`:/dev/webcam`) always stays the same.
 Hence replace webcam2 with webcam3 and so on for every webcam you add and update the physical device that gets passed to the container.
 ```yaml
@@ -291,11 +291,11 @@ Hence replace webcam2 with webcam3 and so on for every webcam you add and update
 ```

 ### Building Docker images locally
-If you'd like to customize the provided Docker Images, you may edit the Dockerfiles within the ``docker/<service>`` Directory.  
-Images are build in multiple stages, the final stage is called ``run``. Based on this, you can update Service definitions within ``docker-compose.override.yaml`` to build Images locally.
+If you'd like to customize the provided Docker Images, you may edit the Dockerfiles within the `docker/<service>` Directory.  
+Images are build in multiple stages, the final stage is called `run``. Based on this, you can update Service definitions within ``docker-compose.override.yaml` to build Images locally.

 Example: Build Moonraker  
-Update the ``image:`` name and add a ``build`` config:
+Update the `image:`` name and add a ``build` config:
 ```yaml
  moonraker:
    image: moonraker:latest
--- a/docker/klipper/README.md
+++ b/docker/klipper/README.md
@@ -105,8 +105,8 @@ none
 ## Tags
 |Tag|Description|Static|
 |---|---|---|
-|`latest`/`nightly`|Refers to the most recent runtime Image for klippy.|May point to a new build within 24h, depending on code changes in the upstream repository.|
-|`<7-digit-sha>` <br>eg: `d75154d`|Refers to a specific commit SHA in the upstream repository. eg: [Klipper3d/klipper:d75154d](https://github.com/Klipper3d/klipper/commit/d75154d695efb1338cbfff061d226c4f384d127b)|Yes|
+|`latest`|Refers to the most recent runtime Image for klippy.|May point to a new build within 24h, depending on code changes in the upstream repository.|
+|`<git description>` <br>eg: `v0.12.0-114-ga77d0790`|Refers to a specific [git description](https://git-scm.com/docs/git-describe#_examples) in the upstream repository. eg: [Klipper3d/klipper:v0.12.0-114-ga77d0790](https://github.com/Klipper3d/klipper/commit/a77d07907fdfcd76f7175231caee170db205ff04)|Yes|
 |`*-tools`|Refers to Debian Image containing all Tools necessary to Build the Microcontroller code for Klipper|Yes|
 |`*-hostmcu`|Refers to the runtime Image for klipper_mcu.|Yes|

--- a/docker/klipperscreen/README.md
+++ b/docker/klipperscreen/README.md
@@ -50,8 +50,8 @@ none
 ## Tags
 |Tag|Description|Static|
 |---|---|---|
-|`latest`/`nightly`|Refers to the most recent runtime Image.|May point to a new build within 24h, depending on code changes in the upstream repository.|
-|`<7-digit-sha>` <br>eg: `37c10fc`|Refers to a specific commit SHA in the upstream repository. eg: [jordanruthe/KlipperScreen:37c10fc](https://github.com/jordanruthe/KlipperScreen/commit/37c10fc8b373944ea138574a44bbfa0a5dcf0a98)|Yes|
+|`latest`|Refers to the most recent runtime Image.|May point to a new build within 24h, depending on code changes in the upstream repository.|
+|`<git description>` <br>eg: `v0.3.8-101-g0226ba0`|Refers to a specific [git description](https://git-scm.com/docs/git-describe#_examples) in the upstream repository. eg: [KlipperScreen/KlipperScreen:v0.3.8-101-g0226ba0](https://github.com/KlipperScreen/KlipperScreen/commit/0226ba0d95fc1b8644a9d1bbf4b7cae7d936b075)|Yes|

 ## Targets
 |Target|Description|Pushed|
--- a/docker/moonraker/README.md
+++ b/docker/moonraker/README.md
@@ -77,8 +77,8 @@ services:
 ## Tags
 |Tag|Description|Static|
 |---|---|---|
-|`latest`/`nightly`|Refers to the most recent runtime Image.|May point to a new build within 24h, depending on code changes in the upstream repository.|
-|`<7-digit-sha>` <br>eg: `d37f91c`|Refers to a specific commit SHA in the upstream repository. eg: [Arksine/moonraker:d37f91c](https://github.com/Arksine/moonraker/commit/d37f91c9c864302e750385297d2aa2a0c9b43035)|Yes|
+|`latest`|Refers to the most recent runtime Image.|May point to a new build within 24h, depending on code changes in the upstream repository.|
+|`<git description>` <br>eg: `v0.8.0-314-gaadff0d`|Refers to a specific [git description](https://git-scm.com/docs/git-describe#_examples) in the upstream repository. eg: [arksine/moonraker:v0.8.0-314-gaadff0d](https://github.com/Arksine/moonraker/commit/aadff0d54e98a536c13d4aca295e3250e06b67b8)|Yes|

 ## Targets
 |Target|Description|Pushed|
--- a/docker/ustreamer/README.md
+++ b/docker/ustreamer/README.md
@@ -44,8 +44,8 @@ none
 ## Tags
 |Tag|Description|Static|
 |---|---|---|
-|`latest`/`nightly`|Refers to the most recent runtime Image.|May point to a new build within 24h, depending on code changes in the upstream repository.|
-|`<7-digit-sha>` <br>eg: `f11d390`|Refers to a specific commit SHA in the upstream repository. eg: [pikvm/ustreamer:f11d390](https://github.com/pikvm/ustreamer/commit/f11d390b2295aff904408f4b38a61bc37a1c4f35)|Yes|
+|`latest`|Refers to the most recent runtime Image.|May point to a new build within 24h, depending on code changes in the upstream repository.|
+|`<git description>` <br>eg: `v5.51-1-g3c7564d`|Refers to a specific [git description](https://git-scm.com/docs/git-describe#_examples) in the upstream repository. eg: [pikvm/ustreamer:v5.51-1-g3c7564d](https://github.com/pikvm/ustreamer/commit/3c7564da19e32badeb858d73bcf98875349dfaff)|Yes|

 ## Targets
 |Target|Description|Pushed|
--- a/scripts/build-images.sh
+++ b/scripts/build-images.sh
@@ -18,21 +18,32 @@ platform="linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64/v8"
 dockerfile=docker/${app}/Dockerfile
 context=$(echo -n ${dockerfile} | rev | cut -f2- -d'/' | rev)

-# Get latest commitref from upstream repo
+# Get get versioning info from upstream repo
+## Set up directories
+pwd=$(pwd)
+tmp=$(mktemp -d)
+## Get upstream repo from Dockerfile
 source=$(grep "ARG REPO" ${dockerfile} | sed -r 's/.*REPO=(.*)$/\1/g')
-ref=$(git ls-remote ${source} HEAD | cut -f1)
-shortref=$(echo -n ${ref} | cut -c 1-7)
+## Clone repo
+git clone ${source} ${tmp} > /dev/null
+## enter repo directory and get infos
+cd ${tmp}
+upstream_version=$(git describe --tags)
+upstream_tags=($(git tag -l --sort='v:refname' | tail -n3))
+upstream_sha=$(git rev-parse HEAD)
+## Return to previous directory and remove tmp
+cd ${pwd}
+rm -rf ${tmp}

 # Set label Values
 label_date=$(date --rfc-3339=seconds)
+label_prind_version=$(git describe --tags)
 if [ "${CI}" == "true" ]; then
-  label_prind_version="${GITHUB_SHA}"
  label_author="${GITHUB_REPOSITORY_OWNER}"
  label_url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}"
  label_doc="${label_url}/blob/${GITHUB_SHA}/docker/${app}/README.md"
  label_src="${label_url}/blob/${GITHUB_SHA}/docker/${app}"
 else
-  label_prind_version="$(git rev-parse HEAD)"
  label_author="$(whoami)"
  label_url="local"
  label_doc="local"
@@ -53,14 +64,14 @@ for target in $(grep "FROM .* as" ${dockerfile} | sed -r 's/.*FROM.*as (.*)/\1/g
  fi

  ## latest
-  if docker buildx imagetools inspect ${registry}${app}:${shortref}${tag_extra} > /dev/null; then
-    log "## Image ${registry}${app}:${shortref}${tag_extra} already exists, nothing to do."
+  if docker buildx imagetools inspect ${registry}${app}:${upstream_version}${tag_extra} > /dev/null; then
+    log "## Image ${registry}${app}:${upstream_version}${tag_extra} already exists, nothing to do."
  else
-    log "## Building latest Image ${registry}${app}:${shortref}${tag_extra}"
+    log "## Building latest Image ${registry}${app}:${upstream_version}${tag_extra}"
    docker buildx build \
-      --build-arg VERSION=${ref} \
+      --build-arg VERSION=${upstream_sha} \
      --platform ${platform} \
-      --tag ${registry}${app}:${shortref}${tag_extra} \
+      --tag ${registry}${app}:${upstream_version}${tag_extra} \
      --tag ${registry}${app}:latest${tag_extra} \
      --label org.prind.version=${label_prind_version} \
      --label org.prind.image.created="${label_date}" \
@@ -68,14 +79,15 @@ for target in $(grep "FROM .* as" ${dockerfile} | sed -r 's/.*FROM.*as (.*)/\1/g
      --label org.prind.image.url="${label_url}" \
      --label org.prind.image.documentation="${label_doc}" \
      --label org.prind.image.source="${label_src}" \
-      --label org.prind.image.version="${ref}" \
+      --label org.prind.image.version="${upstream_version}" \
+      --label org.prind.image.sha="${upstream_sha}" \
      --target ${target} \
      --push \
      ${context}
  fi

  ## Tags
-  for tag in $(git -c 'versionsort.suffix=-' ls-remote --tags --sort='version:refname' --refs ${source} | tail -n3 | rev | cut -f1 -d'/' | rev); do
+  for tag in ${upstream_tags[@]}; do
    if docker buildx imagetools inspect ${registry}${app}:${tag}${tag_extra} > /dev/null; then
      log "## Image ${registry}${app}:${tag}${tag_extra} already exists, nothing to do."
    else
@@ -91,6 +103,7 @@ for target in $(grep "FROM .* as" ${dockerfile} | sed -r 's/.*FROM.*as (.*)/\1/g
        --label org.prind.image.documentation="${label_doc}" \
        --label org.prind.image.source="${label_src}" \
        --label org.prind.image.version="${tag}" \
+        --label org.prind.image.sha="${upstream_sha}" \
        --target ${target} \
        --push \
        ${context}