Search by Tags

TorizonCore Containers Tags and Versioning

 

Article updated at 26 Nov 2020
Subscribe for this article updates

Select the version of your OS from the tabs below. If you don't know the version you are using, run the command cat /etc/os-release or cat /etc/issue on the board.

Torizon 5.0.0

Introduction

Since we constantly update our Debian Containers for Torizon, we assign tags to track their versions. That is important because some container images may be ready to run only on a specific version of Torizon, despite our efforts to make them as independent from the host as possible. It is also important to have versioning because, on embedded systems, it is a good practice to always do testing before deploying a system to production and knowing the exact versions, as well as being able to reproduce it at any given point.

Toradex purposefully does not use the default tag latest. It enforces that specific versions of our containers are being used, preventing customers from incurring a bad practice or using an incompatible version. It means that whenever an image has to be specified, it is required to append a tag. The most common scenarios are:

To make customer's life easier during evaluation, since TorizonCore 5 we add environment variables to TorizonCore with pre-defined values, making it easy to run a compatible container without the need to look-up for the correct values.

Warning: the tags feature is available from TorizonCore 5 onwards!

Prerequisites

Specifying a Tag

By adding a tag to a container image, the version you’d like to run the container with can be specified:

DOCKER_IMAGE_NAME:[TAG]

For instance:

debian:2-bullseye

Release Strategy

There is no defined cadence of releases for TorizonCore containers. New versions of containers are released as soon as new features are added or bugs are fixed.

Semantic Versioning

Torizon containers use the regular MAJOR.MINOR.PATCH versioning and follow largely Semantic Versioning:

MAJOR.MINOR.PATCH-[DATE]-[DEBIAN-RELEASE]

Major

The major number is incremented when compatibility with the current TorizonCore release is broken. Major version is always overwritten when a new backward-compatible container is pushed to Docker Hub, so TorizonCore will always get the updated container when pulling the container with a major number.

[MAJOR] (e.g. 1)

Minor

The minor number is incremented when a new feature is added to the container in a backward-compatible way for the current version of TorizonCore.

MAJOR.[MINOR] (e.g. 1.1) 

Patch

The patch number is incremented when a bug is fixed in the container in a backward-compatible way for the current version of TorizonCore.

MAJOR.MINOR.[PATCH] (e.g. 1.1.1)

Date and Debian release

We also push an additional tag with the date appended.

MAJOR.MINOR.PATCH-[YYYYMMDD] (e.g. 1.0.0-20200819)

Base Debian container comes with the Debian release appended.

MAJOR.MINOR.PATCH-YYYYMMDD-[DEBIAN_RELEASE] (e.g. 1.0.0-20200819-bullseye)

Why We Don’t Tag Containers With "latest"

If a specific tag is not specified, Docker automatically tags it as latest. When a new version of a container is released, it might not be compatible with the version of TorizonCore being used. To avoid this situation, we won’t tag containers with the latest tag, forcing a user to pass a specific tag in Docker commands.

TorizonCore Environment Variables for Container Tags

To make it easier for the customers, TorizonCore provides environment variables to be used with tags, which will pull the latest compatible container version for the currently running version of TorizonCore.

An environment variable is resolved into a compatible tag. From the table below, choose the correct environment variable for your container as a tag. Remember to prepend the variable name with a dollar sign when running a command on Linux, for instance docker run torizon/weston:$CT_TAG_WESTON:

Container Environment variable
kiosk-mode-browser CT_TAG_KIOSK_MODE_BROWSER
qt5-wayland CT_TAG_QT5_WAYLAND
debian CT_TAG_DEBIAN
wayland-base-vivante CT_TAG_WAYLAND_BASE_VIVANTE
qt5-wayland-examples CT_TAG_QT5_WAYLAND_EXAMPLES
weston-vivante CT_TAG_WESTON_VIVANTE
debian-shell CT_TAG_DEBIAN_SHELL
kiosk-mode-browser-x11 CT_TAG_KIOSK_MODE_BROWSER_X11
torizoncore-builder CT_TAG_TORIZONCORE_BUILDER
wayland-base CT_TAG_WAYLAND_BASE
weston CT_TAG_WESTON
qt5-wayland-vivante CT_TAG_QT5_WAYLAND_VIVANTE
qt5-wayland-examples-vivante CT_TAG_QT5_WAYLAND_EXAMPLES_VIVANTE
weston-touch-calibrator CT_TAG_WESTON_TOUCH_CALIBRATOR


The values of the environment variables can also be seen from TorizonCore by using the command:

# env | grep CT_TAG

Build a Container with a Specific Version

There are two ways to build a Debian based container image:

  • Directly on the board
  • On a host development computer

There are several reasons to avoid building directly on the board:

  • It has limited resources
  • Development on the board does not provide a good development ecosystem

You should opt to use the development PC when possible, preferably with our Visual Studio Extension For Torizon or Visual Studio Code Extension for Torizon.

Build on the Board with Tags from Environment Variables

Environmental variables as tags can be also applied in the Dockerfile:

Dockerfile
ARG IMAGE_TAG
FROM torizon/debian:$IMAGE_TAG

Build the image:

# docker build --build-arg IMAGE_TAG=$CT_TAG_DEBIAN .

Build on a Host Development PC with Tags Manually Set

Make sure to Configure the Build Environment for Torizon Containers, especially the Arm emulation. If you use our previously mentioned extensions, they will prompt you to enable Arm emulation, making your life a bit easier.

Since TorizonCore 5 release, we make the use of containers with multi-architecture support. That means, pulling the container on the target will automatically select the container based on your architecture. When cross-compiling on a development host and using a multi-arch container as a base to build your own container, it’s required to select the platform. This can be done in two ways:

  • pass --platform linux/arm or --platform linux/arm64 on the Docker build command line
  • add --platform to the FROM statement in Dockerfile, for instance: FROM --platform=linux/arm64 torizon/debian:[TAG]

You will not be able to use the environment variables, since they are only available on TorizonCore. You need to use the tag values directly.

Dockerfile

Dockerfile
FROM --platform=linux/arm torizon/debian:2-bullseye
…

Note: Please remember that if you once built your image for one architecture, you need to pass the --pull argument to build for another architecture. According to the Docker documentation, the pull argument will always attempt to pull a newer version of the image.

Build the image:

$ docker build --pull .

Dockerfile

Dockerfile
FROM --platform=linux/arm64 torizon/debian:2-bullseye
…

Note: Please remember that if you once built your image for one architecture, you need to pass the --pull argument to build for another architecture. According to the Docker documentation, the pull argument will always attempt to pull a newer version of the image.

Build the image:

$ docker build --pull .

During development, you can manually retrieve the values from the board and export the variables on a terminal in your host computer. You can, for instance, just copy/paste the result from the following command after running it on the board:

# env | grep CT_TAG | awk '{print "export " $0}'