Scenario check refresh need - accetto/ubuntu-vnc-xfce-g3 GitHub Wiki

Check if image refresh is needed

Version: G3v8

Updated: 2025-04-27

Check if image refresh is needed

Introduction

This is a local stage scenario using the second version (G3v2) of the building pipeline.

It's assumed that you have already prepared the local stage as it is described on the page Local building example.

In this scenario we are interested only if a particular image needs to be refreshed.

They are two approaches to this question.

We can generate the up-to-date verbose version sticker value and compare it per human with the already published value. We will call this way Decision by human.

The other approach is to do the comparison per machine. The only difference is, that the machine will need to use the values from the GitHub Gist belonging to the builder repository. We will call this scenario Decision by machine.

You will notice that in these scenarios no permanent images are created. Indeed, only a temporary helper image is needed to answer the question.

So let's check, if the image with Firefox needs to be refreshed. It would be the image accetto/ubuntu-vnc-xfce-g3-firefox.

It is obvious, that if you will perform these scenario sometimes later, your actual results will be probably different.

By building images locally, we are not always interested if anything has changed since the previous release. We often want to build the image in any case and therefore we can simply skip the building the helper image.

However, there are also other reasons for executing the pre_build hook script, which builds the helper image.

It is then, when we want to build our target image with the updated version-sticker labels. That scenario is described on the page Build new image releases.

The other reason could be the refreshing of the g3-cache. However, this can be done also by the executing of the cache hook script directly.

Also, since the version G3v7 of the building pipeline, the build hook script uses the temporary helper image as an external cache. It's also responsible for deleting it afterwards.

Using an external cache significantly speeds up the building of the final image.

Remark: Actually, the simplest way of building images is to use the provided utility script ci-builder.sh (check the page Local building example for more information). However, here we wanted to illustrate the concepts.

Decision by human

In this case we don't need to do any additional configuration.

We can go straight ahead and execute the hook script pre_build. It will build a temporary helper image, store the version sticker values into the temporary helper files.

Note that since the pipeline G3v7, the helper image will not be deleted by the pre_build hook script, but the build hook script, after using it as an external cache.

The first time we often also want to refresh the Docker builder's cache, so we provide the additional argument --no-cache:

### PWD = project's root directory

./docker/hooks/pre_build dev latest-firefox --no-cache
### or also
./builder.sh latest-firefox pre_build --no-cache

After the building finishes, we look at the end of the script's console output (or in the file scrap_builder.log if we've used the second alternative). There should be the text similar to the following one:

Current verbose version sticker:
FEATURES_BUILD_SLIM_FIREFOX=1
FEATURES_BUILD_SLIM_NOVNC=1
FEATURES_BUILD_SLIM_TOOLS=1
FEATURES_BUILD_SLIM_XFCE=1
FEATURES_BUILD_SLIM_XSERVER=1
FEATURES_FIREFOX=1
FEATURES_NOVNC=1
FEATURES_SCREENSHOOTING=
FEATURES_THUMBNAILING=
FEATURES_USER_GROUP_OVERRIDE=
FEATURES_VERSION_STICKER=1
FEATURES_VNC=1
Firefox 106.0.2
jq 1.6
Mousepad 0.4.2
nano 4.8
noVNC 1.3.0
Python 3.8.10
TigerVNC 1.12.0
Ubuntu 20.04.5
websockify 0.10.0

Building of new image has not been forced.
Getting the previous verbose version sticker value from the builder gist '3787004467036fe4940486be37b748e0'
Gist file 'devops-headless-ubuntu-g3@[email protected]' saved as './docker/scrap-version_sticker-verbose_previous.tmp'.
Comparing verbose version stickers
Verbose version sticker has not changed since the last build, no need for building a new image.

Demanding building stop

Current version sticker of 'accetto/devops-headless-ubuntu-g3:latest-firefox_helper': ubuntu20.04.5-firefox106.0.2

Removing helper image
Untagged: accetto/devops-headless-ubuntu-g3:latest-firefox_helper
Deleted: sha256:4165d4a32a2c3b62d6805a64c20f4fe66efeddc91ab378c40ad85c59cce5b7b0

We are interested only in the first part of the output, because that is the actual up-to-date value of the verbose version sticker.

Next we will go to the image accetto/ubuntu-vnc-xfce-g3-firefox published on the Docker Hub and we will click the version sticker badge by the tag latest. The page containing its verbose version sticker will be displayed and we can compare both contents.

At the time of writing, the values are the same. However, if you will perform this scenario later, there will be probably some differences.

You can spot the sentence Verbose version sticker has changed, a new image will be built., which has no real meaning in this case. We haven't prepared the environment, so the hook script could not access the GitHub Gist belonging to the builder repository even if it would exist.

Therefore the helper file scrap-version_sticker-verbose_previous.tmp, which has been created in the folder ./docker/, is empty.

The other two helper files, scrap-version_sticker_current.tmp and scrap-version_sticker-verbose_current.tmp, contain the correct up-to-date values. They would be used by other hook scripts.

You can also see from the console output, that the helper image has been named accetto/devops-headless-ubuntu-g3:latest-firefox-helper:latest.

Why this name? These are the reasons:

I have set the repository owner's name to accetto (environment variable REPO_OWNER_NAME).
I've set the builder repository name to devops-headless-ubuntu-g3 (environment variable BUILDER_REPO)
I've provided the input arguments dev and latest-firefox to the hook script pre_build and according to the code in the file env.rc it resulted into the image tag latest-firefox.
According to the variable ${helper_suffix} in the file env.rc, the helper image name got the suffix -helper and it gets no explicit tag.

The same naming rules are followed in all cases. However, the helper image name suffix is specific to the pre_build hook script.

Decision by machine

This is actually the case of executing the first part of the building pipeline.

The decision making is very similar to the previous case, only the previous verbose version sticker value is got from the GitHub Gist belonging to the builder repository.

Because of that, it is required that the GitHub Gist exists and that the previous verbose version sticker value has previously been published to it.

We need to prepare the environment, so the local machine can access the GitHub Gist. The environment variable GIST_ID needs to be set.

The course of action is almost the same as it has been described above.

We will execute the hook script pre_build with the same two arguments as previously. This time we will assume, that the builder's cache has already been refreshed, so we will not use the additional --no-cache argument.

### PWD = project's root directory

./docker/hooks/pre_build dev latest-firefox
### or also
./builder.sh latest-firefox pre_build

Here is the interesting part of the output log:

Current verbose version sticker:
FEATURES_BUILD_SLIM_FIREFOX=1
FEATURES_BUILD_SLIM_NOVNC=1
FEATURES_BUILD_SLIM_TOOLS=1
FEATURES_BUILD_SLIM_XFCE=1
FEATURES_BUILD_SLIM_XSERVER=1
FEATURES_FIREFOX=1
FEATURES_NOVNC=1
FEATURES_SCREENSHOOTING=
FEATURES_THUMBNAILING=
FEATURES_USER_GROUP_OVERRIDE=
FEATURES_VERSION_STICKER=1
FEATURES_VNC=1
Firefox 106.0.2
jq 1.6
Mousepad 0.4.2
nano 4.8
noVNC 1.3.0
Python 3.8.10
TigerVNC 1.12.0
Ubuntu 20.04.5
websockify 0.10.0

Building of new image has not been forced.
Getting the previous verbose version sticker value from the builder gist '3787004467036fe4940486be37b748e0'
Gist file 'devops-headless-ubuntu-g3@[email protected]' saved as './docker/scrap-version_sticker-verbose_previous.tmp'.
Comparing verbose version stickers
Verbose version sticker has not changed since the last build, no need for building a new image.

Demanding building stop

Current version sticker of 'accetto/devops-headless-ubuntu-g3:latest-firefox_helper': ubuntu20.04.5-firefox106.0.2

We can see, that the decision is correct: Verbose version sticker has not changed since the last build, no need for building a new image..

Indeed, the helper file scrap-version_sticker-verbose_previous.tmp is not empty this time and its content is identical to the file scrap-version_sticker-verbose_current.tmp:

FEATURES_BUILD_SLIM_FIREFOX=1
FEATURES_BUILD_SLIM_NOVNC=1
FEATURES_BUILD_SLIM_TOOLS=1
FEATURES_BUILD_SLIM_XFCE=1
FEATURES_BUILD_SLIM_XSERVER=1
FEATURES_FIREFOX=1
FEATURES_NOVNC=1
FEATURES_SCREENSHOOTING=
FEATURES_THUMBNAILING=
FEATURES_USER_GROUP_OVERRIDE=
FEATURES_VERSION_STICKER=1
FEATURES_VNC=1
Firefox 106.0.2
jq 1.6
Mousepad 0.4.2
nano 4.8
noVNC 1.3.0
Python 3.8.10
TigerVNC 1.12.0
Ubuntu 20.04.5
websockify 0.10.0

There is also a new helper file named scrap-demand-stop-building.

The file is empty, but its sheer presence would cause, that the rest of the building pipeline would be skipped.

This behavior can be overridden by deleting the file or by setting the environment variable FORCE_BUILDING=1.

Similarly, setting the environment variable PROHIBIT_BUILDING=1 would prevent the building of the image.

Pivotal image groups

There are always some images in each of the sibling projects, that have more weight by deciding if the project's image set needs a refresh, than the other ones.

Such images are members of the pivotal image group, which is defined in the script ci-builder.sh.

Since the version G3v8 (Release 25.05) you can list the pivotal images using one of the new ci-builder.sh commands.

The list command will output the names of both the build and deployment target images.

Just a reminder: The build target image is the the image, which is built on the local building stage. It's name is defined by the environment variable BUILDER_REPO. The deployment target image is the same image published to the repository on the Docker Hub. Its name is defined by the environment variable DEPLOYMENT_REPO or DEPLOYMENT_REPO_CHROMIUM or DEPLOYMENT_REPO_FIREFOX.

./ci-builder.sh list group pivotal

How I refresh `accetto` images

This section describes how I check if and what images require a refresh.

First, I prepare the environment by ensuring that the environment variable FORCE_BUILDING is not set to 1. It should be undefined or set to zero:

### there should be no output or only zero ('0')
ubuntu-vnc-xfce-g3> echo $FORCE_BUILDING

Be sure to check also the file docker/hooks/secrets.rc because the variable FORCE_BUILDING can be set also there.

Just a reminder: The file docker/hooks/secrets.rc is sourced by the hook script env.rc, which itself is sourced by almost any other script.

Second, I build the pivotal images locally without pushing them to the Docker Hub. Without pushing, the building is usually pretty fast.

ubuntu-vnc-xfce-g3> ./ci-builder.sh all-no-push group pivotal

Then I use the digest command to review the results. For example, in the following case all the pivotal images are up-to-date.

ubuntu-vnc-xfce-g3> ./ci-builder.sh log get digest

### output example
--> Log digest:

Building image 'headless-ubuntu-g3:focal'
Building image 'headless-ubuntu-g3:focal-chromium'
Building image 'headless-ubuntu-g3:focal-firefox'
Building image 'headless-ubuntu-g3:jammy'
Building image 'headless-ubuntu-g3:jammy-chromium'
Building image 'headless-ubuntu-g3:jammy-firefox'
Building image 'headless-ubuntu-g3:latest'
Building image 'headless-ubuntu-g3:latest-chromium'
Building image 'headless-ubuntu-g3:latest-firefox'
No build needed for 'headless-ubuntu-g3:focal'.
No build needed for 'headless-ubuntu-g3:focal-chromium'.
No build needed for 'headless-ubuntu-g3:focal-firefox'.
No build needed for 'headless-ubuntu-g3:jammy'.
No build needed for 'headless-ubuntu-g3:jammy-chromium'.
No build needed for 'headless-ubuntu-g3:jammy-firefox'.
No build needed for 'headless-ubuntu-g3:latest'.
No build needed for 'headless-ubuntu-g3:latest-chromium'.
No build needed for 'headless-ubuntu-g3:latest-firefox'.

If, however, there would be no line like No build needed for 'headless-ubuntu-g3:latest-firefox'., then I can already conclude, that all images that are based on Ubuntu 24.04 and include Firefox, require a refresh. It includes also the images of the sibling project accetto/headless-drawing-g3.

Just a remark: After mostly unsatisfactory experience in the past I've decided against the automated updating of accetto images on the Docker Hub. There are too many moving parts and I've also found, that it's not really so critical to use the latest version of each particular utility. So I still prefer a human maintainer to be involved. Also, if a fresh image version is needed, you can always build it ad-hoc using the builder utilities builder.sh or ci-builder.sh. It really takes just a minute.

There is also the option of updating in a running container, like this:

sudo apt-get update
sudo apt-get upgrade

### or adding some 'new-utility'
sudo apt-get update
sudo apt-get install <new-utility>