Build new image releases

Version: G3v8

Updated: 2025-04-27

---

• Build new image releases
  • Introduction
  • Quick and simple
  • Current version-sticker labels
  • How I refresh accetto images

Introduction

This is a local stage scenario using the seventh version (G3v7) 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.

Our goal is to build a new release of an existing image.

This scenario could be performed after the scenario Check if image refresh is needed, but it depends on it only in some cases.

Typically it is necessary to execute the hook script pre_build first only in the following cases:

• If you first want to check, if the image needs to be refreshed.

• If you want, that the new image has the current version-sticker label value.

• If you want to execute the complete building pipeline.

Let's build a new release of the image with Firefox. It would be the image accetto/ubuntu-vnc-xfce-g3-firefox.

However, on our current local stage the image will be named accetto/devops-headless-ubuntu-g3:latest-firefox.

Why this name? It is explained on the page Check if image refresh is needed.

They are actually only two simple scenarios in this case, because building images using this building pipeline is really easy.

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.

Quick and simple

In this case we are interested only in quick building of a new image locally.

We do not care about the value of the version-sticker label. We are also not interested in the publishing the image or its README file to the Docker Hub.

Building the image in this case is really simple. We don't need to do any additional configuration and we also don't need to execute the pre_build hook script first.

We can execute the hook script build straight away. We will assume that the builder's cache has already been refreshed, so we will not use the additional argument --no-cache.

However, there is one catch.

Make sure that the temporary helper file docker/scrap-demand-stop-building doesn't exist. It could have been left by previous building attempts.

The presence of the file has the meaning of no build is needed and it will cause the build hook script to exit without building any images.

There will be the message Demanding building stop in the log in such case.

The helper temporary files are all named likescrap-*.tmp and they are normally created by the hook script pre_build, which also cares about removing the old ones. That's why we have to remove them manually if we skip the pre_build hook script.

### PWD = project's root directory

./docker/hooks/build dev latest-firefox
### or alternatively (with the 'scrap_builder.log')
./builder.sh latest-firefox build

That's all. We should get our new image accetto/headless-ubuntu-g3:latest-firefox. Assuming we've cared about the old temporary helper files, as described above.

Why this name? The image name is defined by the environment variable BUILDER_REPO and the tag by the blend command line parameter. In this case the values were BUILDER_REPO="headless-ubuntu-g3"and latest-firefox.

The building itself should be really quick and its console output is not so interesting. Maybe only the lines that show that the current g3-cache content has been used and nothing needed to be downloaded:

==> G3-CACHE hit file 'tigervnc-1.13.1.x86_64.tar.gz' in section 'tigervnc'

==> G3-CACHE hit file 'v1.6.0.tar.gz' in section 'novnc'

==> G3-CACHE hit file 'v0.13.0.tar.gz' in section 'websockify'

Or the line, which shows the actual building time:

Current timestamp: 2025-04-27T10:45:48Z

Let's check, if this value is indeed stored in the label created of the new image:

docker inspect accetto/devops-headless-ubuntu-g3:latest-firefox

Scroll down to the Labels part of the output:

"Labels": {
    "any.accetto.built-by": "docker",
    "any.accetto.version-sticker": "null",
    "org.label-schema.vcs-ref": "4554d59",
    "org.label-schema.vcs-url": "https://github.com/accetto/ubuntu-vnc-xfce-g3",
    "org.opencontainers.image.authors": "accetto",
    "org.opencontainers.image.created": "2025-04-27T10:45:48Z",
    "org.opencontainers.image.description": "Headless Ubuntu/Xfce/VNC/noVNC containers with Internet browsers",
    "org.opencontainers.image.documentation": "https://github.com/accetto/ubuntu-vnc-xfce-g3",
    "org.opencontainers.image.ref.name": "ubuntu",
    "org.opencontainers.image.source": "https://github.com/accetto/ubuntu-vnc-xfce-g3",
    "org.opencontainers.image.title": "accetto/ubuntu-vnc-xfce-g3",
    "org.opencontainers.image.url": "https://github.com/accetto/ubuntu-vnc-xfce-g3",
    "org.opencontainers.image.vendor": "https://github.com/accetto",
    "org.opencontainers.image.version": "latest-firefox"
}

You can see, that the correct building time is stored in the image metadata even by the straight-away building.

On the other hand, the value of the version-sticker label is currently null. Let's fix it in the next scenario.

Current version-sticker labels

This scenario is almost identical to the previous one, with the difference that we want to persist the correct current version-sticker label value.

We can get it by executing the hoot script pre_build first. It will care about the temporary helper files as it is described above or on the page Check if image refresh is needed.

However, if the pre_build will decide, that no build is needed, as it's explained on the page Check if image refresh is needed, then it will create the build-stopper file scrap-demand-stop-building. We have to delete it before executing the build hook script.

To ensure that the new image will be built in any case, we can set the environment variable FORCE_BUILDING=1. There will be the message Building of new image has been forced. in the log in the case when it would be normally skipped.

This is the complete building example:

### PWD = project's root directory

### building the helper image assuming FORCE_BUILDING=1
./docker/hooks/pre_build dev latest-firefox
### or also
./builder.sh latest-firefox pre_build

### building the final deployment image
./docker/hooks/build dev latest-firefox
### or also
./builder.sh latest-firefox build

You can check, that the pre_build script has built the helper image accetto/headless-ubuntu-g3_latest-firefox-helper:latest. Since the pipeline version G3v7 (Release 25.03) this image is not automatically removed by the pre_build script because it will be used by the build script as an external cache. However, since the version G3v8 (Release 25.05) it's still removed if the build script would be skipped. It's when the file scrap-demand-stop-building is present.

The helper image will be removed by the build script, which will use it as an external cache and therefore it will build the final deployment image accetto/headless-ubuntu-g3:latest-firefox really very fast.

Let's inspect the Labels of the final deployment image:

"Labels": {
    "any.accetto.built-by": "docker",
    "any.accetto.version-sticker": "ubuntu24.04.2-firefox136.0.4",
    "org.label-schema.vcs-ref": "4554d59",
    "org.label-schema.vcs-url": "https://github.com/accetto/ubuntu-vnc-xfce-g3",
    "org.opencontainers.image.authors": "accetto",
    "org.opencontainers.image.created": "2025-04-27T10:56:14Z",
    "org.opencontainers.image.description": "Headless Ubuntu/Xfce/VNC/noVNC containers with Internet browsers",
    "org.opencontainers.image.documentation": "https://github.com/accetto/ubuntu-vnc-xfce-g3",
    "org.opencontainers.image.ref.name": "ubuntu",
    "org.opencontainers.image.source": "https://github.com/accetto/ubuntu-vnc-xfce-g3",
    "org.opencontainers.image.title": "accetto/ubuntu-vnc-xfce-g3",
    "org.opencontainers.image.url": "https://github.com/accetto/ubuntu-vnc-xfce-g3",
    "org.opencontainers.image.vendor": "https://github.com/accetto",
    "org.opencontainers.image.version": "latest-firefox"
}

We can see, that the version-sticker label really contains the value ubuntu24.04.2-firefox136.0.4, which is the correct current value at the time of building the image.

How I refresh accetto images

On the page Check if image refresh is needed I've described how I approach the problem of keeping the images in accetto DockerHub repositories up to date.

---