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:

• When running a command on the board, as docker pull or docker run.
• When writing a Dockerfile using our containers as base in the command FROM.

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

• Finish our Quickstart Guide
• Understand our Debian container offerings by reading Debian Containers for Torizon
• Learn how to modify a TorizonCore Debian based container images

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:

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.

• ARM 32
• ARM 64

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

$ docker build --pull .

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

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