Search by Tags

Debian Container for Torizon

Applicable for

Article updated at 22 Nov 2019
Compare with Revision

Subscribe for this article updates


Along with TorizonCore, Toradex provides a set of Debian-based containers as a friendly starting environment. The containers are derived from the official Debian images and are optimized to be used on TorizonCore. There are console only base containers and containers which make use of a modern Wayland based graphic stack using the Weston Wayland Compositor. In this article we go through how to start using the proposed containers.

This article complies to the Typographic Conventions for Torizon Documentation.


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

  • Computer on Module with Torizon installed.
  • (optional) Basic understanding of Docker and docker run command options.

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 which allows to start 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 execute the command:

# docker run -d --rm --name=weston-container --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
# docker run -d --rm --name=weston-container --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
# docker run -e ACCEPT_FSL_EULA=1 -d --rm --name=weston-container --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

This will ask Docker to run a container with the name weston-container using the torizon/arm32v7-debian-weston:buster container image. 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 iMX6, parallel RGB on Colibri iMX6/iMX7). The container will be started in background, you can look at the Weston output for debugging by using the Docker logs subcommand:

# docker logs weston-container

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/iMX6ULL you must use weston-launch --tty=/dev/tty7 --user=torizon -- --use-pixman to start Weston with Pixman.

Weston creates a Unix socket file so graphical client application 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. E.g. this example reuses the same image to run a second container, but this time using es2gears_wayland.

For Apalis/Colibri iMX6/iMX7 use this command:

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

For Apalis iMX8/Colibri iMX8X currently there is no es2gears available. Use this command to start the Weston Terminal (this command also enables access rights to /dev/galcore):

# docker run -e ACCEPT_FSL_EULA=1 -d --rm --name=es2gears-container --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

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/ e…"   31 seconds ago      Up 28 seconds                           es2gears-container
f4a426310353        torizon/arm32v7-debian-weston:buster   "/usr/bin/ -…"   3 minutes ago       Up 3 minutes                            weston-container
# docker exec -it weston-container /bin/bash

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

Install Debian Packages Permanently

The article Install Debian Packages on Target shows how to install Debian packages on the target and create a new Docker image from it.