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

Check if image refresh is needed

Version: G3v2

Updated: 2022-11-04


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.

Remark: Actually we can build images really simply by using the provided utility script ci-builder.sh (check the page Local building example for more information). However, we want to illustrate some concepts here.

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 and then remove the helper image.

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.

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 code in the file env.rc, the helper image name got the suffix _helper.

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.