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

Modifying Torizon OS Debian Based Container Images


Toradex provides Docker Debian-based container images. In order to take full advantage of them, this article will show you how to modify them to fit your necessities, here are two ways to modify our container images:

  • Run commands directly in a container (useful only to develop the Dockerfile or for quick prototyping)
  • Write Dockerfile (most commonly used and recommended method)

This article complies with the Typographic Conventions for Torizon Documentation.


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

Build a Container based on Torizon's Debian-based Docker Images​

Working in the Container​

It is common to quickly test changes in a running container before you actually build your own customized container image. This can also be a useful method to debug issues that can occur when building a container image.

Let's start by running the base Debian image.

# docker run -it torizon/debian:$CT_TAG_DEBIAN /bin/bash

This should place you in a terminal prompt within the Debian container.

From here you can execute commands and install any package provided by the Debian distribution. For example perhaps you'd want the nano text editor.

## apt update && apt install nano

As you can see by just running commands in the container directly you can quickly validate and test your customized container.

It should be noted that this method should only be used for early development and that to truly create your own container image a Dockerfile should be used.

Writing a Dockerfile​

In this section we will actually build a container image in a way that is reproducible and can be versioned controlled. For these reasons this should generally be the go-to method when modifying another container image.

Begin by creating a file named Dockerfile, this acts as the "source" file for a container image. In this case we are going to add the nano text editor like we did in the above section:


FROM torizon/debian:$CT_TAG_DEBIAN

RUN apt update && apt install nano -y


A standard Dockerfile has no extension, therefore make sure your file is not named Dockerfile.txt, especially since file extensions are hidden by default. Consult this lesson's FAQ for details about naming.

After creating the file, you can log in to your Docker account:

$ docker login

Now that you are logged to your credentials and the file was created, it's time to finally build your image:

$ docker build --build-arg CT_TAG_DEBIAN="3-bookworm" -t <username>/<my-container-image> .

Here we can see how working with Dockerfiles have a similar workflow to standard software development (change -> build -> push). For more information on Dockerfiles please reference the official Docker documentation here.

Deploying to the Board​

Deploying applications to the board is a topic on its own. Please read the dedicated article Deploying Container Images to Torizon OS.

Docker Multi-stage Build​

Downloading the final image takes a lot of time and space, so it's very important to keep it tiny. With multi-stage builds, you can build a docker image in stages with multiple FROM instructions in your Dockerfile. Each FROM instruction starts a new build stage and you can copy only the layers which are necessary from the previous stage. This is very useful to avoid including build dependencies in your final image and it also becomes easier to understand.

For more information, please refer to Docker Multistage documentation.

Send Feedback!