Skip to main content
Version: Torizon OS 6.x.y

Torizon Containers Tags and Versioning

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, there are environment variables in Torizon OS with pre-defined values, making it easy to run a compatible container without the need to look-up for the correct values.

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:3-bookworm

Release Strategy​

There is no defined cadence of releases for Torizon Debian 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 Torizon OS release is broken. Major version is always overwritten when a new backward-compatible container is pushed to Docker Hub, so Torizon OS 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 Torizon OS.

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 Torizon OS.

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. 3.0.0-20221121-bookworm)

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 Torizon OS 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.

Torizon OS Environment Variables for Container Tags​

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

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:

ContainerEnvironment variable
chromiumCT_TAG_CHROMIUM
cogCT_TAG_COG
debianCT_TAG_DEBIAN
qt5-waylandCT_TAG_QT5_WAYLAND
qt5-wayland-examplesCT_TAG_QT5_WAYLAND_EXAMPLES
qt5-wayland-examples-vivanteCT_TAG_QT5_WAYLAND_EXAMPLES_VIVANTE
qt5-wayland-vivanteCT_TAG_QT5_WAYLAND_VIVANTE
qt6-waylandCT_TAG_QT6_WAYLAND
qt6-wayland-examplesCT_TAG_QT6_WAYLAND_EXAMPLES
qt6-wayland-examples-vivanteCT_TAG_QT6_WAYLAND_EXAMPLES_VIVANTE
qt6-wayland-vivanteCT_TAG_QT6_WAYLAND_VIVANTE
wayland-baseCT_TAG_WAYLAND_BASE
wayland-base-vivanteCT_TAG_WAYLAND_BASE_VIVANTE
westonCT_TAG_WESTON
weston-touch-calibratorCT_TAG_WESTON_TOUCH_CALIBRATOR
weston-vivanteCT_TAG_WESTON_VIVANTE

The values of the environment variables can also be seen from Torizon OS 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 the Torizon IDE Extension.

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.

Toradex provides 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 Torizon OS. You need to use the tag values directly.

Dockerfile
FROM --platform=linux/arm torizon/debian:3-bookworm
…
info

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}'


Send Feedback!