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

Debian Containers for Torizon

Introduction​

Toradex provides a set of lightweight, Debian-based Docker container images for Torizon, derived from the Debian Slim Image variant of Debian 12 Bookworm. These containers serve as foundations for application development on Torizon, offering a hierarchy of images with minimal installed packages and disabled manual pages.

While you can use any container, Toradex's containers simplify tasks such as:

  • Running graphical applications.
  • Accessing specific hardware features like GPU and VPU.
  • Utilizing maintained images tested for specific modules.
  • Operating without running as root by default.

The container offerings include:

  • Console-only base container.
  • Container with a modern Wayland-based Weston compositor.
  • Qt-Wayland-based container supporting common Qt backends like Wayland and EGLFS.
  • Chromium and Cog-based containers for displaying web content and single-page applications.
  • .NET Containers for both Console and GUI applications.
  • Containers containing Cross-Compilers.
  • Containers to test products during the hardware bring-up phase.

Each container builds upon the previous one, adding more features to closely match the minimal dependencies of various applications. Being Debian-based, they allow further package installation using the apt command as required by user applications. The container images are freely available on Docker Hub. These containers are also used as a base when using the templates from the Torizon IDE extension.

This article complies with the Typographic Conventions for Torizon Documentation.

Platform-Specific Torizon Debian Containers​

Toradex supports variations of the same container images for each of the SoC families present in the Toradex portfolio. This is due to the specific userspace libraries needed to properly use the vendor-maintained kernels.

Each SoC-specific container has the SoC family name in the container name, following the <container-registry-user>/<container-name>-<soc-platform-name>:<tag> format. For example, the container responsible for the Wayland-based Weston compositor for the AM62 SoC for the major 4 release is torizon/weston-am62:4. Another example is the console-only base Debian image for the i.MX 8 platform, named torizon/debian-imx8:4.

Additionally, Toradex provides containers that don't have a platform specifier appended to the image names (using the previous example, this image would be just torizon/weston). These images are used when the upstream kernel is selected to be shipped with Torizon OS (for the i.MX 6 and i.MX 7 families, for example).

Each SoC-specific container family has a custom Debian package feed maintained by Toradex, with the packages themselves being attested from Toradex GitHub builds under the torizon organization.

Note that the same packages might have different versions across platforms. For example, on Torizon OS 7, Toradex ships Weston 12 for i.MX 8 devices while shipping Weston 10 for the i.MX 6 and i.MX 7. In general, the strategy is to cover the Toradex test suite and not break use cases during a major release. For platforms that heavily rely on non-upstreamed forks such as iMX8, the strategy is to ship the same versions of key userspace applications that one would get if using Yocto. There is no list of these 'key' applications, but in general, these are applications that require special code to use hardware-specific features, such as GPU acceleration, such as Weston, OpenCV, Chromium, etc.

Differences from Upstream Debian Images​

The Toradex feed has a higher priority than the upstream Debian repositories, so apt installs the Toradex-validated packages instead of the upstream versions.

You can also use upstream Debian images on Torizon OS. If you do, consider the following differences:

  • Package versions might differ from the ones shipped in the Debian Containers for Torizon.
  • Hardware-specific optimizations, such as GPU acceleration, might not be available.

Container Version Matrix​

A list of all the currently supported platforms and each container for a given platform follows:

NameTag
aspdotnet10-imx954
aspdotnet8-imx954
chromium-imx954
cog-imx954
cross-toolchain-arm64-imx954
cross-toolchain-ssh-arm64-imx954
debian-imx954
dotnet10-gtk3-imx954
dotnet10-imx954
dotnet10-wayland-imx954
dotnet8-gtk3-imx954
dotnet8-imx954
dotnet8-wayland-imx954
graphics-tests-imx954
qt5-wayland-examples-imx954
qt5-wayland-imx954
qt6-wayland-examples-imx954
qt6-wayland-imx954
qt6-wayland-tests-imx954
tensorflow-lite-dev-imx954
tensorflow-lite-examples-imx954
tensorflow-lite-imx954
wayland-base-dev-imx954
wayland-base-imx954
wayland-gtk3-imx954
weston-imx954
weston-touch-calibrator-imx954
Tag 3 Containers
Name
chromium-am62
cog-am62
debian-am62
graphics-tests-am62
qt5-wayland-am62
qt5-wayland-examples-am62
qt6-wayland-am62
qt6-wayland-examples-am62
wayland-base-am62
weston-am62
Tag 2 Containers
Name
chromium
cog
graphics-tests
qt5-wayland
qt5-wayland-examples
rt-tests
stress-tests
wayland-base
weston
weston-touch-calibrator
Tag 1 Containers
Name
qt5-wayland
qt5-wayland-examples
wayland-base
weston
weston-touch-calibrator

Tags and Versioning​

Toradex Debian container images use semantic versioning for releases and are tagged accordingly. Notably, Toradex avoids using the latest tag, which is the default tag when pulling an image without tags. Instead, Toradex recommends users use the CT_TAGS environment variables that are available in all Torizon OS deployments. To learn more, read the dedicated article Torizon OS Containers Tags and Versioning.

Each Torizon OS major version uses a specific container major tag, such as torizon/debian-imx8:4 for Torizon OS 7. To check the major tag for each Torizon OS version, see Debian Release Mapping. Toradex neither guarantees nor tests that images built for Torizon OS 7 are compatible with Torizon OS 6.

Debian Release Mapping​

Each Torizon major version is paired with a specific Debian stable release. Toradex moves the Debian Containers for Torizon to a new Debian major release only together with a new Torizon major release.

The following table lists the Debian release for each Torizon major version:

Torizon OS VersionDebian ReleaseContainer Major Tag
Torizon OS 7Debian 12 Bookworm4
Torizon OS 6Debian 12 Bookworm3
Torizon OS 5Debian 11 Bullseye2

Platform Architecture​

In contrast with previous versions of Torizon Debian, images are built for the specific architecture of the SoC family (for example, the i.MX 8 family only contains 64-bit cores, so all images for those particular devices are only built for the arm64 instruction set architecture) with the exception of the upstream images (those images that do not contain a SoC specifier), which are built for arm64, armv7 and amd64 architectures.

When pulling an image, the architecture choice matches the host's, although it is possible to specify the intended architecture by passing the --platform argument. Similarly, when building on top of Torizon images, docker build --pull --platform=<IMAGE_ARCH> ... can be used to specify the build architecture.

For example, if you want to pull an image for the 32-bit armv7 architecture, use the following command:

$ docker pull --platform=linux/arm/v7 <image-name>

For arm64v8, use:

$ docker pull --platform=linux/arm64/v8 <image-name>

Details about Toradex Images​

This section gives more details about Toradex Debian-based images and how they can improve the development process.

Two points from the Toradex base image (which are carried through to the other images that inherit from it) are worth highlighting. For this, please take a look at the upstream variant base Dockerfile hosted on GitHub.

Firstly, Toradex configures a default, non-root torizon user inside each container. The user is added to the correct groups by a custom script which simplifies permissions and access to the base Torizon OS system from the container.

Dockerfile
COPY users-groups.sh /users-groups.sh
RUN ./users-groups.sh \
    && rm users-groups.sh

Secondly, the enablement of the package repository feed provided by Toradex is performed by the following Dockerfile instructions:

Dockerfile
echo "Types: deb\n\
URIs: https://feeds1.toradex.com/debian/snapshots/$TORADEX_SNAPSHOT\n\
Suites: testing\n\
Components: main non-free\n\
Signed-By: /usr/share/keyrings/toradex-debian-repo.gpg" > /etc/apt/sources.list.d/toradex.sources \
    && echo "Package: *\nPin: origin feeds1.toradex.com\nPin-Priority: 900" > /etc/apt/preferences.d/toradex-feeds

For more information about how the Toradex custom Debian feeds enable hardware acceleration from the container, read the Toradex engineering-oriented blog about Hardware Acceleration in Containers.

Additionally, each image has automated tests for the hardware-specific portions, which guarantee that the hardware and kernel are working properly with the base containers. For more information about tests and the Toradex release cycle, refer to the Containers Tags and Versioning page.

You can browse the Toradex GitHub repository torizon/torizon-containers and see exactly what is included in each of the Toradex Debian images.

Support and Security Updates​

Support Period​

Support for Debian Containers for Torizon ends at whichever comes first: the Torizon OS EOL or the end of Debian security support for the paired release, including the Debian Long Term Support (LTS) period. For the complete policy, see Debian Containers Support.

Security Updates​

Debian stable releases receive security fixes throughout their support period. Debian backports fixes for known vulnerabilities to the stable release without moving packages to a new upstream version. The Debian Security Team provides these fixes during regular support, and the Debian LTS team provides them during the LTS period. In most cases, Debian provides the fix for your Debian release, so you do not need to update Torizon OS or move to a newer Debian release to receive it. You need a new Torizon major version only to move to a newer Debian major release, or when the support period of your container major version ends.

For Toradex and SoC-specific packages, Debian does not provide security fixes; the Torizon team handles them when a vulnerability requires an update.

To get the latest security fixes in your application container:

  • Rebuild your container image regularly on top of the latest Debian Containers for Torizon for your Torizon OS major version.

  • Update the installed packages as part of your Dockerfile, for example:

    Dockerfile
    ARG CT_TAG_DEBIAN
    FROM torizon/debian-imx8:$CT_TAG_DEBIAN

    RUN apt-get update && apt-get upgrade -y \
        && rm -rf /var/lib/apt/lists/*

    Set CT_TAG_DEBIAN to the container major tag of your Torizon OS version when you build the image, for example, docker build --build-arg CT_TAG_DEBIAN=4 . for Torizon OS 7.

CVE Handling​

When a vulnerability scanner reports a CVE in your container, evaluate it in the context of your application:

  • Assess whether an attacker can exploit the CVE in your product. A CVE in a package does not always mean that your product is exploitable. Consider whether your application uses the affected component, how the component is exposed, and what your threat model is.
  • Check the status of the CVE for your Debian release in the Debian Security Tracker. Debian does not fix every CVE in every release. For example, a package can be out of scope for Debian LTS. In that case, apt-get upgrade does not fix the CVE.
  • If Debian does not provide a fix for your release, check whether your application needs the affected package. If it does not, remove the package from your container image.
  • Use the Torizon Vulnerability Manager to track vulnerabilities across your fleet.

Next Steps​

Send Feedback!