Search by Tags

Debian Containers for Torizon

 

Article updated at 15 Sep 2020
Compare with Revision




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

Toradex provides Docker container images for Torizon that derive from a minimal variant of the Bullseye release of Debian. The purpose is to provide a hierarchy of light images with disabled manual pages and a minimalist set of installed packages that can be used as a foundation for developing customer's applications.

Toradex also provides development tools for pin configuration, display settings, performance monitoring and more, with both local and web-based remote UIs. Please refer to Torizon Related Articles to have more information.

This article complies to the Typographic Conventions for Torizon Documentation.

Prerequisites

To have a better understanding of this article, the following prerequisites are recommended:

To get the most from this article and test things in practice, we recommend that you clone the torizon-samples repository to your computer:

$ cd ~
$ git clone --branch=bullseye https://github.com/toradex/torizon-samples.git
$ cd torizon-samples/debian-container

Debian Containers

Toradex has designed a set of Debian-based container images to serve as foundations for application development in Torizon. The containers offer interesting features such as:

  • Console only base container;
  • Container which makes use of a modern Wayland based graphics stack using the Wayland protocol and a compositor (Weston) running in a separate container;
  • Qt-Wayland based container, a full graphics stack container image.

Each container is built on top of a previous one, adding an increased set of features. There is a diversity of containers available in order to more closely match the minimum dependencies of applications that may be developed on top of them. As the containers are Debian based, specific packages can be further installed with the apt command as required by user's applications.

The following diagram depicts the hierarchy of these containers in TorizonCore 5. The container images can be freely retrieved from Docker Hub.


  • Debian based container images

    Debian based container images

Besides the core containers above, Toradex also offers Debian-based containers with development tools to be executed directly in modules (e.g. device tree overlay management), as well as ample containers for demonstrating key features of Toradex hardware and useful application concepts.

Details about our Images

This section gives more details about our Debian based images and how they can improve the development process. Please take a look at our base Dockerfile hosted on GitHub.

Torizon containers are based in the Debian slim Image. From the start of the base Dockerfile:

Dockerfile
ARG IMAGE_ARCH=linux/arm/v7 # For arm64v8 use: # ARG IMAGE_ARCH=linux/arm64/v8 ARG IMAGE_TAG=bullseye-20200908-slim ARG DEBIAN_SNAPSHOT=20200908T070000Z ARG ADD_TORADEX_REPOSITORY=1 FROM --platform=$IMAGE_ARCH debian:$IMAGE_TAG AS base

Two important considerations arise from the above snippet:

  1. Torizon images are multi-platform aware. The architecture is automatically chosen based on the architecture of the host. If pulling a Torizon image results in a wrong architecture, docker pull --platform=<IMAGE_ARCH> ... can be used to forcefully specify the intended architecture. Similarly, when building on top of Torizon images, docker build --pull --platform=<IMAGE_ARCH> ... can be used to enforce the build architecture as well.
  2. Torizon images are currently based in a snapshot of Debian Bullseye. This is due to the fact that Bullseye is not yet a stable Debian distribution, and consequently it can change in ways that are incompatible with Toradex software.

The Dockerfile also adds a user and group ID to match those used by the host OS:

Dockerfile
RUN groupadd --gid 1000 torizon \ && useradd --gid 1000 --uid 1000 --create-home torizon

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

Dockerfile
ADD https://feeds.toradex.com/debian/toradex-debian-repo.gpg /etc/apt/trusted.gpg.d/ RUN chmod 0644 /etc/apt/trusted.gpg.d/toradex-debian-repo.gpg \ && echo "deb https://feeds.toradex.com/debian/ testing main non-free" >>/etc/apt/sources.list \ && echo "Package: *\nPin: origin feeds.toradex.com\nPin-Priority: 900" > /etc/apt/preferences.d/toradex-feeds

Debian With Weston Wayland Compositor

Weston is a Wayland based compositing window manager, basically the piece of software which makes sure that graphical application can be drawn alongside each other. Weston comes with a minimal launcher that allows starting a terminal, but in embedded configurations, the launcher is often disabled/hidden.

The container is Debian Bullseye release based, featuring the Weston Wayland compositor. To pull the container and start it on the module, choose your hardware from the tabs below and follow the instructions given:

Start weston using the torizon/weston container image:

# docker run -d --rm --name=weston --net=host --cap-add CAP_SYS_TTY_CONFIG \
             -v /dev:/dev -v /tmp:/tmp -v /run/udev/:/run/udev/ \
             --device-cgroup-rule='c 4:* rmw' --device-cgroup-rule='c 13:* rmw' --device-cgroup-rule='c 226:* rmw' \
              torizon/weston:$CT_TAG_WESTON --developer weston-launch --tty=/dev/tty7 --user=torizon

Start weston using the torizon/weston container image:

# docker run -d --rm --name=weston --net=host --cap-add CAP_SYS_TTY_CONFIG \
             -v /dev:/dev -v /tmp:/tmp -v /run/udev/:/run/udev/ \
             --device-cgroup-rule='c 4:* rmw' --device-cgroup-rule='c 13:* rmw' --device-cgroup-rule='c 226:* rmw' \
              torizon/weston:$CT_TAG_WESTON --developer weston-launch --tty=/dev/tty7 --user=torizon -- --use-pixman

Start weston using the torizon/weston-vivante container image:

Attention: Please, note that by executing the following line you are accepting the terms and conditions of the NXP's End-User License Agreement (EULA)

# docker run -e ACCEPT_FSL_EULA=1 -d --rm --name=weston --net=host --cap-add CAP_SYS_TTY_CONFIG \
             -v /dev:/dev -v /tmp:/tmp -v /run/udev/:/run/udev/ \
             --device-cgroup-rule='c 4:* rmw' --device-cgroup-rule='c 13:* rmw' --device-cgroup-rule='c 199:* rmw' --device-cgroup-rule='c 226:* rmw' \
              torizon/weston-vivante:$CT_TAG_WESTON_VIVANTE --developer weston-launch --tty=/dev/tty7 --user=torizon

If the container image is not preinstalled, Docker will download it from Docker Hub and store it on the module -- this will require an internet connection on the device and may take a few minutes. It will start Weston (HDMI on Apalis SoMs, parallel RGB on Colibri SoMs, MIPI-DSI on Verdin SoMs). The container will be started in the background, you can look at the Weston output for debugging by using the Docker logs subcommand:

# docker logs weston

Most of the arguments in this command line make sure that the container can access the necessary hardware (display controller, GPU and input devices) and be notified about hardware changes (through TorizonCore's udev daemon).

On modules without GPU like Colibri iMX7 we add weston-launch --tty=/dev/tty7 --user=torizon -- --use-pixman to start Weston with Pixman.

Weston creates a Unix socket file so graphical client applications can communicate with it (typically in the 1000-runtime-dir directory under /tmp). By bind mounting /tmp into a second container, a Wayland client application can access the Wayland compositor despite being in separate containers. The Wayland client application will talk to Weston (the Wayland Compositor) through the Unix socket file and draw in a window on Weston.

As an example, let's start a second container that reuses the same image, but brings up an application on top of the Wayland compositor. Select your module from the tabs below and follow the instructions:

In order to launch a container named wayland-app and start the weston-terminal, run this command:

# docker run -d --rm --name=wayland-app --user=torizon \
             -v /dev/dri:/dev/dri -v /tmp:/tmp \
             --device-cgroup-rule='c 226:* rmw' \
             torizon/weston:$CT_TAG_WESTON weston-terminal

In order to launch a container named wayland-app and start the weston-terminal, run this command:

Attention: Please, note that by executing the following line you are accepting the terms and conditions of the NXP's End-User License Agreement (EULA)

# docker run -e ACCEPT_FSL_EULA=1 -d --rm --name=wayland-app --user=torizon \
             -v /dev/dri:/dev/dri -v /dev/galcore:/dev/galcore -v /tmp:/tmp \
             --device-cgroup-rule='c 199:* rmw' --device-cgroup-rule='c 226:* rmw' \
             torizon/weston-vivante:$CT_TAG_WESTON_VIVANTE weston-terminal

Note: you are also giving access to /dev/galcore, meaning you can leverage the Vivante graphics acceleration inside the container.

To get a shell inside the container docker exec can be used:

# docker ps
CONTAINER ID        IMAGE                                  COMMAND                  CREATED             STATUS              PORTS               NAMES
ab83ec23855e        torizon/weston:1   "/usr/bin/entry.sh e…"   31 seconds ago      Up 28 seconds                           wayland-app
f4a426310353        torizon/weston:1   "/usr/bin/entry.sh -…"   3 minutes ago       Up 3 minutes                            weston
# docker exec -it weston /bin/bash

This will create a prompt with root privileges inside the container.

Demonstration

Before we move into the explain section, go to the demonstration folder. Make sure that you have followed the instructions provided in this article's Prerequisites first:

$ cd demonstration

On the board, make sure that all containers are stopped:

# docker stop $(docker ps -a -q)

Docker-compose is used to start multiple containers at the same time, providing shared data volumes, mount points, resource usage limitations and other advantages. You can have a good experience using docker compose to start our containers and take a glimpse of the development environment, in this case, the demo is showing a browser in kiosk-mode using three containers:

  • torizon/weston:2 or torizon/weston-vivante:2: The Wayland compositor;

  • portainer/portainer: provides the data that should be displayed by the UI;

  • torizon/kiosk-mode-browser:2 based on the torizon/wayland-base:2 container, it runs a browser in a kiosk-mode, allowing implementation of web-based UIs.

Select your hardware in the box below:

Attention: By starting the demonstration using this docker compose file, you are accepting the NXP's End-User License Agreement (EULA).

Then you can start the demo with a single command:

# docker-compose -f <your-docker-compose-file> up

Note: With the above command, you directly attach to the containers you are about to start. To start in detached-mode, you can append -d to the above command. Note: To use the device_cgroup_rules configuration option we have to use Compose file version 2.4 currently.

Next Steps

Torizon 4.0.0

Introduction

Toradex provides Debian based container images that derive from a minimal variant of the buster release of Debian. The purpose is to provide for our costumers a light image with disabled manual pages and suggested package installation, limiting dependencies only to required ones.

Our objective is also to provide development tools for pin configuration, display settings, performance monitoring and more, with both local and web-based remote UIs. Please refer to Torizon Related Articles to have more information.

This article complies to the Typographic Conventions for Torizon Documentation.

Prerequisites

To have a better understanding of this article the following prerequisites are recommended:

To get the most from this article and test things in practice, we recommend that you clone the torizon-samples repository to your computer:

$ cd ~
$ git clone https://github.com/toradex/torizon-samples.git
$ cd torizon-samples/debian-container

Debian Containers

We provide a set of Debian-based container images with different features:

  • Console only base container

  • Container which makes use of a modern Wayland based graphics stack using the Wayland protocol and a compositor (Weston) running in a separate container

  • Qt-Wayland based container, a full graphics stack container image

  • Debian based docker container with development tools to run on the module (a.e. device tree overlay)

Each container image is based on a Debian distribution so you can pull in alternative components with apt, just need to make sure that they have the Arm architecture variant.


  • Debian based container images

    Debian based container images

Warning: If you find some issues while testing any arm64v8 container image on Apalis iMX8 and Colibri iMX8X, please don't hesitate to report them. Toradex appreciates your feedback since iMX8 modules are not a very well tested platform on Torizon.

Details about our Images

Attention: please use the tag buster-20200415 if you are using the TorizonCore Monthly release from April, a.k.a 4.0.0-devel-202004+build.3. At the moment you should only use the tag buster if you are using a newer release of TorizonCore.

This section is going to give you more details about our Debian based images and how they can improve your development process. Please take a look at our base Dockerfile hosted on GitHub.

We use the Debian slim Image to create our container.

Dockerfile
FROM $IMAGE_ARCH/debian:10.2-slim

In these two lines, a user group ID to match those used by host OS were added.

Dockerfile
RUN groupadd --gid 1000 torizon \ && useradd --gid 1000 --uid 1000 --create-home torizon

In the box below, a custom repository feed provided by Toradex with some useful packages was added.

Dockerfile
ARG ADD_TORADEX_REPOSITORY=1 RUN if [ "$ADD_TORADEX_REPOSITORY" = "1" ]; then \ echo "deb https://feeds.toradex.com/debian/testing/ buster main" >> /etc/apt/sources.list ; \ echo "Package: *\nPin: origin feeds.toradex.com\nPin-Priority: 900" > /etc/apt/preferences.d/toradex-feeds ; \ fi

Debian With Weston Wayland Compositor

Weston is a Wayland based compositing window manager, basically the piece of software which makes sure that graphical application can be drawn alongside each other. Weston comes with a minimal launcher that allows starting a terminal, but in embedded configurations, the launcher is often disabled/hidden.

The container is Debian buster release based, featuring the Weston Wayland compositor. To pull the container and start it on the module, choose your hardware from the tabs below and follow the instructions given:

Start weston using the torizon/arm32v7-debian-weston:buster container image:

# docker run -d --rm --name=weston --net=host --cap-add CAP_SYS_TTY_CONFIG \
             -v /dev:/dev -v /tmp:/tmp -v /run/udev/:/run/udev/ \
             --device-cgroup-rule='c 4:* rmw' --device-cgroup-rule='c 13:* rmw'  --device-cgroup-rule='c 226:* rmw'\
              torizon/arm32v7-debian-weston:buster --developer weston-launch --tty=/dev/tty7 --user=torizon

Start weston using the torizon/arm32v7-debian-weston:buster container image:

# docker run -d --rm --name=weston --net=host --cap-add CAP_SYS_TTY_CONFIG \
             -v /dev:/dev -v /tmp:/tmp -v /run/udev/:/run/udev/ \
             --device-cgroup-rule='c 4:* rmw'  --device-cgroup-rule='c 13:* rmw' --device-cgroup-rule='c 226:* rmw' \
              torizon/arm32v7-debian-weston:buster --developer weston-launch --tty=/dev/tty7 --user=torizon -- --use-pixman

Start weston using the torizon/arm64v8-debian-weston-vivante:buster container image:

Attention: Please, note that by executing the following line you are accepting the terms and conditions of the NXP's End-User License Agreement (EULA)

# docker run -e ACCEPT_FSL_EULA=1 -d --rm --name=weston --net=host --cap-add CAP_SYS_TTY_CONFIG \
             -v /dev:/dev -v /tmp:/tmp -v /run/udev/:/run/udev/ \
             --device-cgroup-rule='c 4:* rmw'  --device-cgroup-rule='c 13:* rmw' --device-cgroup-rule='c 199:* rmw' --device-cgroup-rule='c 226:* rmw' \
              torizon/arm64v8-debian-weston-vivante:buster --developer weston-launch --tty=/dev/tty7 --user=torizon

Since the container image is not preinstalled, Docker will download it from Docker Hub and store it on the module. This will require an internet connection on the device and may take a few minutes. It will start Weston (HDMI on Apalis SoMs, parallel RGB on Colibri SoMs, MIPI-DSI on Verdin SoMs). The container will be started in the background, you can look at the Weston output for debugging by using the Docker logs subcommand:

# docker logs weston

Most of the arguments in this command line make sure that the container can access the necessary hardware (display controller, GPU and input devices) and be notified about hardware changes (through TorizonCore's udev daemon).

On modules without GPU like Colibri iMX7 we add weston-launch --tty=/dev/tty7 --user=torizon -- --use-pixman to start Weston with Pixman.

Weston creates a Unix socket file so graphical client applications can communicate with it (typically in the 1000-runtime-dir directory under /tmp). By bind mounting /tmp into a second container, a Wayland client application can access the Wayland compositor despite being in separate containers. The Wayland client application will talk to Weston (the Wayland Compositor) through the Unix socket file and draw in a window on Weston.

As an example, let's start a second container that reuses the same image, but brings up an application on top of the Wayland compositor. Select your module from the tabs below and follow the instructions:

In order to launch a container named wayland-app and start es2gears, run this command:

# docker run -d --rm --name=wayland-app --user=torizon \
             -v /dev/dri:/dev/dri -v /tmp:/tmp \
             --device-cgroup-rule='c 226:* rmw' \
             torizon/arm32v7-debian-weston:buster es2gears_wayland

In order to launch a container named wayland-app and start the weston-terminal, run this command:

Attention: Please, note that by executing the following line you are accepting the terms and conditions of the NXP's End-User License Agreement (EULA)

# docker run -e ACCEPT_FSL_EULA=1 -d --rm --name=wayland-app --user=torizon \
             -v /dev/dri:/dev/dri -v /dev/galcore:/dev/galcore -v /tmp:/tmp \
             --device-cgroup-rule='c 199:* rmw' --device-cgroup-rule='c 226:* rmw' \
             torizon/arm64v8-debian-weston-vivante:buster weston-terminal

Note: you are also giving access to /dev/galcore, meaning you can leverage the Vivante graphics acceleration inside the container.

To get a shell inside the container docker exec can be used:

# docker ps
CONTAINER ID        IMAGE                                  COMMAND                  CREATED             STATUS              PORTS               NAMES
ab83ec23855e        torizon/arm32v7-debian-weston:buster   "/usr/bin/entry.sh e…"   31 seconds ago      Up 28 seconds                           wayland-app
f4a426310353        torizon/arm32v7-debian-weston:buster   "/usr/bin/entry.sh -…"   3 minutes ago       Up 3 minutes                            weston
# docker exec -it weston /bin/bash

This will create a prompt with root privileges inside the container.

Demonstration

Before we move into the explain section, go to the demonstration folder:

$ cd demonstration

On the board, make sure that all containers are stopped:

# docker stop $(docker ps -a -q)

Docker-compose is used to start multiple containers at the same time, providing shared data volumes, mount points, resource usage limitations and other advantages. You can have a good experience using docker compose to start our containers and take a glimpse of the development environment, in this case, the demo is showing a browser in kiosk-mode using three containers:

  • Weston: Wayland compositor

  • Portainer: provides the data that should be displayed by the UI

  • Kiosk-mode-browser: based on torizon- arm32v7-debian-wayland container, that can be used to run a browser in a kiosk-mode, allowing implementation of web-based UIs

Select your hardware in the box below:

Note: Use "-e ACCEPT_FSL_EULA=1" to accept the NXP EULA or set the environment variable on every invocation by uncommenting the corresponding line in "docker-compose.arm64.yml".

Then you can start the demo with a single command:

# docker-compose -f <your-docker-compose-file> up

Note: With the above command, you directly attach to the containers you are about to start. To start in detached-mode, you can append -d to the above command. Note: To use the device_cgroup_rules configuration option we have to use Compose file version 2.4 currently.

Next Steps