Skip to main content
Version: Torizon OS 7.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. 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.

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:4

Release Strategy​

There is no defined cadence of releases for Torizon Debian containers. New versions of containers are published in the following situations:

  1. A new stable Debian version gets released (including point releases): all images for all platforms are rebuilt.
  2. A feature or bugfix gets merged into the Torizon Containers repository.

Tests​

Automated tests run for:

  1. Against a nightly release of Torizon OS, with either the next or stable-rc tags.
  2. Against a stable release of Torizon OS, with either the next or stable-rc tags.

Tests can be found in the Torizon Containers Repository tests directory and users can run them locally with the provided container. For more developer-oriented information about the Torizon Container tags and tests, please read the README file in the repo itself.

Semantic Versioning​

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

MAJOR.MINOR.PATCH

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.

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.

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.

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, 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:

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, meaning the latest stable major.

An environment variable is resolved into a compatible tag. From the table below, choose the correct environment variable for your container and use it as a tag. Remember to prepend the variable name with a dollar sign when running a command on Linux and to select the correct platform for your specific SoM. For instance, running Weston with an i.MX8 SoM would be docker run torizon/weston-imx8:$CT_TAG_WESTON.

More information about the SoC-specific containers can be found in the Debian Containers for Torizon article.

ContainerEnvironment variable
chromium<-platform>CT_TAG_CHROMIUM
cog<-platform>CT_TAG_COG
debian<-platform>CT_TAG_DEBIAN
qt5-wayland<-platform>CT_TAG_QT5_WAYLAND
qt5-wayland-examples<-platform>CT_TAG_QT5_WAYLAND_EXAMPLES
qt6-wayland<-platform>CT_TAG_QT6_WAYLAND
qt6-wayland-examples<-platform>CT_TAG_QT6_WAYLAND_EXAMPLES
wayland-base<-platform>CT_TAG_WAYLAND_BASE
weston<-platform>CT_TAG_WESTON
weston-touch-calibrator<-platform>CT_TAG_WESTON_TOUCH_CALIBRATOR

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!