Search by Tags

Pre-provisioning Docker Containers onto a TorizonCore image

 

Article updated at 17 Feb 2021
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.



Remember that you can always refer to the Torizon Documentation, there you can find a lot of relevant articles that might help you in the application development.

Torizon 5.0.0

Introduction

In this article, we cover how to use TorizonCore Builder Tool to pre-provisioning Docker Containers onto a TorizonCore image to be deployed on several units in a production line using Toradex Easy Installer.

Production Programming vs Torizon OTA

The workflow described in this article adds container images to the actual installer image that can be flashed to the hardware for production programming. It is different from how container updates are applied with Torizon OTA: from the Torizon OTA dashboard, once you upload your Docker Compose file, the running TorizonCore OS will pull the containers during runtime and replace the current pre-existent Docker Compose file.

In summary, here's when you should use each:

  • Pre-provision container images onto TorizonCore: to be used when you are preparing your own custom TorizonCore image for production programming, allowing it to boot with your containers from the first time, without the need to pull those from the internet.
  • Upload container images to Torizon OTA: to be used when you want to update the application on a running fleet of TorizonCore devices, without the need to re-flash the devices or update OS images into Torizon OTA.

Read the article Deploying Container Images to TorizonCore for a more comprehensive overview of all the methods for deploying containers to a TorizonCore image on various steps of the development cycle.

This article complies to the Typographic Conventions for Torizon Documentation.

Prerequisites

To complete these instructions you need:

Pre-provisioning Docker Containers onto a TorizonCore image

Here we assume you are working on a directory containing the unpacked TorizonCore Easy Installer image without containers.

If you have downloaded an installer image as a tarball, you can unpack it with tar. For example, for a tarball file named torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12.tar, we would run:

$ tar xvf <file-location>/torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12.tar

This would give us, in this case, a directory called torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12 that represents our source installer image.

The process to preinstall or pre-provision Docker Containers onto that installer image comprises two stages:

  • Bundle the Docker Containers: This step creates a tarball containing all the containers as well as a Docker Compose file referencing those containers using a specific hash.
  • Combine the Docker Containers Bundle with a TorizonCore image: In this step, the tool takes a Toradex Easy Installer image of TorizonCore (with the Docker engine) and combines it with the previously bundled Docker Containers.

Bundle the Docker Containers

To create a bundle you need an input Docker Compose file. As an example, we will use a simple docker-compose file:

docker-compose.yml
version: '2.4'
 
services:
  hello-world: 
    image: hello-world

With that file present in your working directory, you can then employ the torizoncore-builder bundle command.

$ torizoncore-builder bundle docker-compose.yml

The container bundle tarball along with a modified version of the Docker Compose file will be located at the new directory bundle/ in your working directory.

In case you are referencing multi-platform container images, the above command will likely fail because no platform was specified. To solve this, you should pass the --platform switch selecting the appropriate platform which depends on the target device.

For devices based on i.MX6/i.MX7 based SoMs:

$ torizoncore-builder bundle --platform=linux/arm/v7 docker-compose.yml

And for those based on i.MX8 based SoMs:

$ torizoncore-builder bundle --platform=linux/arm64 docker-compose.yml

Note: Pass the --platform switch to torizoncore-builder bundle when working with multi-platform Docker images.

Combine the Docker Containers Bundle with a TorizonCore image

At this point, you should have the following directory/file structure relative to your working directory:

├── bundle
├── docker-compose.yml
└── torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12
    ├── image.json
    ├── ...
    └── wrapup.sh

Where torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12 is the source image without containers. Now we can create a new image bundling the containers in it by running:

$ torizoncore-builder combine --image-directory torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12 --output-directory image_output

After running this process, a combined TorizonCore image will be available in the output directory specified by the --output-directory switch. This image is ready to be installed into the SoM using Toradex Easy Installer

Remarks About Using Private Registries

If you are using a private Docker registry, you will need to pass other command-line options. For a quick reference, run torizoncore-builder bundle --help or read the TorizonCore Builder Tool - The Bundle Command.

For Torizon OTA, you will also have to add the private registry credentials to the TorizonCore image. Read the article Using Private Registries With Torizon OTA for more details.

Torizon 4.0.0

Introduction

This article shows how to preinstall or pre-provision a Docker Containers onto a TorizonCore image with a Docker engine. This process is especially useful when preparing an image to be flashed on several units in production.

In this article, we show how to preinstall a Docker Container onto a TorizonCore image using either a Linux Host PC or a Windows machine.

The process comprises two stages:

  • Bundle the Docker Containers: This step creates a tarball containing all the containers as well as a Docker Compose file, which references those containers using a specific hash.

  • Combine the Docker Containers Bundle with a TorizonCore image: In this step, the script takes a Toradex Easy Installer image of TorizonCore with the Docker engine and combines it with the previously bundled Docker Containers.

The process makes use of Docker in Docker, which requires the script to have access to the host Docker engine.

This article complies to the Typographic Conventions for Torizon Documentation.

Pre-requisites

The pre-requisite to complete these instructions are:

Using TorizonCore builder on Linux

Preparation

Make sure to use an empty working directory and navigate to it. This directory is shared (bind-mounted) with the container this tool runs in, and it stores temporary files and the final image.

$ mkdir ~/myworkdir/
$ cd ~/myworkdir/

Inside the myworkdir directory, create the image and image_output folders.

$ mkdir image image_output

For convenience, create an alias called torizoncore-builder for the container execution:

$ alias torizoncore-builder='docker run --rm -it -v $(pwd):/workdir --net=host \
-v /var/run/docker.sock:/var/run/docker.sock torizon/torizoncore-builder'

Note: The bind mounts of the host Docker need to match the location inside the torizoncore-builder script (/builder). For that reason, you should use this alias (torizoncore-builder) only in this directory which it was created.

Gather the image file and the docker-compose file

Copy your project's docker-compose.yml file to the working directory.

As an example, we will use a simple docker-compose file:

docker-compose.yml
version: '2.4'
 
services:
  hello-world: 
    image: hello-world

Add the .tar file containing the TorizonCore Image with no-container pre-provisoned for offline instalation to the image directory.

After copying these two files to the working directory, we check its content:

$ tree .
.
├── docker-compose.yml
├── image
│   └── teziimage.tar
└── image_output

Create a container bundle

With the files on the directory, call the bundle command to create a container bundle:

$ torizoncore-builder bundle --host-workdir=$(pwd) --platform=linux/arm/v7 --file docker-compose.yml

Attention: Replace --platform=linux/arm/v7 by --platform=linux/arm/v8 when using a 64-bit SoC (iMX8).

This step downloads the Docker in Docker container image and uses the docker-compose.yml template to download all images referenced in this Docker Compose file. The tool then compresses the complete set of Docker containers on a tar file.

The container bundle tarball will be located at the new directory ./bundle/.

Combine the container images bundle with TorizonCore image

Before running this step, make sure to have a TorizonCore image tarball available in your work directory, as explained earlier.

To combine the container images bundle with TorizonCore image:

$ torizoncore-builder combine --image-directory ./image --output-directory ./image_output

After running this process, a combined TorizonCore image is available in the output directory specified by the --output-directory flag. This image is ready to be installed into the SoM using Toradex Easy Installer

Using TorizonCore builder on Windows 10

Warning: This procedure requires Windows 10 with WSL2 installed

To execute the following instructions, the Windows Subsystem for Linux version 2(WSL2) is necessary. WSL2 is available when updating Windows 10 to the version 2004 (Build 19041) or higher.

Preparation

Open the Windows command prompt (cmd) and make sure to use an empty working directory and navigate to it. This directory is shared (bind-mounted) with the container this tool runs in, and it stores temporary files and the final image.

C:\Users\My User>mkdir myworkdir/
C:\Users\My User>cd myworkdir/
C:\Users\My User\myworkdir>

Inside the myworkdir directory, create the image and image_output folders.

C:\Users\My User\myworkdir>mkdir image
C:\Users\My User\myworkdir>mkdir image_output

Gather the image file and the docker-compose file

Copy your project's docker-compose.yml file to the working directory.

As an example, we will use a simple docker-compose file:

docker-compose.yml
version: '2.4'
 
services:
  hello-world: 
    image: hello-world

Add the .tar file containing the TorizonCore Image with no-container pre-provisoned for offline instalation to the image directory.

After copying these two files to the working directory, we check the myworkdir directory content:

├── docker-compose.yml
├── image
│   └── teziimage.tar
└── image_output

Create a container bundle

With the files on the directory, call the bundle command to create a container bundle:

C:\Users\My User\myworkdir>docker run --rm -it --net=host ^
-v "C:\Users\My User\myworkdir":/workdir -v /var/run/docker.sock:/var/run/docker.sock ^
torizon/torizoncore-builder bundle --host-workdir="/c/Users/My User/myworkdir" ^
--platform=linux/arm/v7 --file docker-compose.yml

Attention: Replace --platform=linux/arm/v7 by --platform=linux/arm/v8 when using a 64-bit SoC (iMX8).

This step downloads the Docker in Docker container image and uses the docker-compose.yml template to download all images referenced in this Docker Compose file. The tool then compresses the complete set of Docker containers on a tar file.

The container bundle tarball will be located at the new directory ./bundle/.

Combine the container images with TorizonCore

Before running this step, make sure to have a TorizonCore image tarball available in your work directory, as explained earlier.

To combine the container images bundle with TorizonCore image:

C:\Users\My User\myworkdir>docker run --rm -it --net=host ^
-v "C:\Users\My User\myworkdir":/workdir -v /var/run/docker.sock:/var/run/docker.sock ^
torizon/torizoncore-builder combine --image-directory image ^
--output-directory image_output

After running this process, a combined TorizonCore image is available in the output directory specified by the --output-directory flag. This image is ready to be installed into the SoM using Toradex Easy Installer