Skip to main content
Version: 6

Deploying Container Images to TorizonCore

Introduction​

The Torizon platform uses containers to package applications that can, in turn, be deployed to the TorizonCore OS. In other words, when you want to deploy a container to TorizonCore, you are looking at a means to deploy your application or part of it to your computer on module.

You can deploy container images in a few ways, and the method depends on the phase of the development cycle:

Possibilities for Container Deployment

During development:

  • From our IDE extensions: this is the preferred option during development because it will abstract away the deployment process. You need to hit Run or F5, and the extension automatically deploys the application and your containers with remote debugging enabled.
  • From the Command-line Interface (CLI): you can manually deploy images if you don't want to use our IDE extensions or Torizon Platform. There are a few different CLI methods with their advantages and disadvantages.
  • From the Portainer container manager (GUI): due to being a container manager, you cannot build and deploy container images to a registry; therefore, you must choose the IDE Extensions or the command-line for that. With Portainer, you can only pull and run containers on the board.

During production:

  • With the TorizonCore Builder: you can generate a custom TorizonCore image that includes your containers, among other customization. This is meant for flashing the board during production, using Toradex Easy Installer.
  • From Torizon Platform: it is a good and convenient way to deploy application updates to a device or a fleet of devices. You will most likely start using it after flashing the board with TorizonCore.

See a summary of the processes described above in the following diagram:

Deploy Container To The Board Flowchart

Prerequisites​

During Development​

IDE Extensions​

The IDE extensions make your life easier by abstracting away the deployment of containers during development. While preparing for production, you can use the extensions to build the containers in "release" mode and then deploy them to the board using the methods described in this article's sections about Torizon Platform or CLI further on. You can also use the Torizon IDE Backend Command-line Interface to integrate build, deployment, and publishing operations in your CI/CD pipelines.

Refer to the IDE extension articles for more information about deploying containers to the board:

Command-line Interface (CLI)​

You have a couple of options when it comes to deployment from the command-line:

  • Online registry push and pull: you use the convenient docker push and docker pull commands to push and pull images, by default, to Docker Hub. It has the drawback that you always must communicate to the Docker Hub - or another online registry server - which is not ideal for development.
  • Local registry push and pull: the idea is the same as the previous one, except you keep a local registry and don't need a connection with the online registry. It's faster, and you keep things inside of your LAN. It is a nice approach for development.
  • Docker save and load: you use the commands docker save and docker load to pack/unpack the entire image in a compressed tar file. While you can do development on a LAN, it does deploy the whole image every time, instead of layers. On the other hand, you don't need to set up a local registry.

See them in more detail below in the following sub-sections.

info

username refers to your Docker Hub username, which is also your namespace inside the Docker Hub. my-container-image to the container image name you are building/pulling.

Online Registry Push and Pull​

The first option is to use the traditional docker push/pull method to push to Docker Hub. This method requires a Docker Hub account to push your container image to. First, we push the container image.

$ docker push <username>/<my-container-image>

Now your container image can be accessed on any other device such as your computer on module running TorizonCore.

# docker pull <username>/<my-container-image>

For other container registries, you can use the same commands, but you'll need to tag your image with the explicit registry:

<container-registry>/<username-or-namespace>/<my-container-image>

Please refer to the documentation of the container registry you plan to use, such as Amazon ECR or the Azure Container Registry.

Local Registry Push and Pull​

First, you must setup a local registry. While it can get fancy, you need to run a single command on your development PC to get the basics running:

$ docker run -d -p 5000:5000 --restart=always --name registry registry:2

You must make sure that your image tags are pointing to your local registry. You can either build them already with the local registry tag or create an additional tag for an existing image:

Build with tag pointing to local registry
$ docker build -t localhost:5000/<my-container-image> .

Create an additional tag for an existing image, pointing to the local registry. You can get the tag from the latest container image build. 
$ docker tag <my-container-image-tag> localhost:5000/<my-container-image>

Then on your local PC, you can use docker push, and docker pull commands as described in the previous section of this article, except you must prefix the image names with your local registry (often you want to push since you are cross-building for the target):

$ push
docker push localhost:5000/<my-container-image>

$ pull
docker pull localhost:5000/<my-container-image>

On the board, before being able to push and pull, you need to create a rule to allow an insecure registry. Remember that we only go through the basics, but you can setup a secure local Docker registry if you want or need to. On the board, create a file named /etc/docker/daemon.json and add your local registry's PC IP and port to the insecure registries:

/etc/docker/daemon.json
{
  "insecure-registries" : ["IP-of-my-PC:5000"]
}

Reboot or restart the Docker daemon on the board:

# sudo reboot

or

# sudo systemctl restart docker

Push and pull to your local registry from your board (often you want to pull since you are cross-building on the PC, not on the board):

$ push
docker push localhost:5000/<my-container-image>

# pull
docker pull <IP-of-my-PC>:5000/<my-container-image>

Keep in mind, if you are having trouble, consult the Docker documentation:

Docker Save and Load​

The other option for deployment uses docker load/save. Save your docker image as a portable tar archive file:

$ docker save -o my-dockerfile.tar <username>/my-dockerfile

Copy this tar archive to your target device:

$ scp my-dockerfile.tar torizon@X.X.X.X:/home/torizon/

Load the tar archive, which will then put the container image on your target device:

# docker load -i my-dockerfile.tar

Run and Manage Containers from the Command-line​

When the container is available either in a Docker registry or on the board, you can follow the next steps by reading the article Run and Manage Containers with Portainer and the Command-line on Torizon. It describes in-depth how to run a container on the board.

Portainer​

Portainer does not provide features to build or deploy container images.

Portainer can only be used to run and manage containers. For this, the container image needs to be available online or locally. If you are building a container by yourself, you can use the previous sections' methods to achieve this.

Run and Manage Containers from Portainer​

Once the container is available, read the article Run and Manage Containers with Portainer and the Command-line on Torizon. It describes in-depth the steps for running a container on the board.

During Production​

TorizonCore Builder - Toradex Easy Installer​

The TorizonCore Builder Tool is a command-line tool run on the host computer. Among several features, one of them is to add containers to a fresh (sometimes called vanilla) TorizonCore image.

First of all, make sure to deploy your image to a Docker registry using either docker pull, as described in the previous section Online Registry Push and Pull, or from the Docker extension for VS Code. The registry must be accessible from your computer.

Write a Docker Compose file for your application, as described in the Using Multiple Containers with TorizonCore or have one generated for you if using our IDE Extensions.

Follow the instructions provided in the dedicated article Pre-provisioning Docker Containers onto a TorizonCore image to create a custom Easy Installer image of Torizon with your pre-provisioned Docker container images.

Finally, use the Toradex Easy Installer Tool to install this custom Easy Installer image of Torizon into the internal flash memory of Toradex modules in an extremely simple way.

To learn more about deploying application containers in Torizon-based devices during production, please read our Production Programming & Provisioning article.

Torizon Platform​

The Torizon Platform Services server does not store container images. Instead, it uses Docker Compose files containing all the information required to run the board's containers.

If using the Visual Studio Code Extension for Torizon or the Visual Studio Extension For Torizon, there is a command that pushes the container image to a docker registry and adds your application to the Torizon Platform Services.

If not using the IDE Extensions, first of all, make sure to deploy your image to an online Docker registry using either docker pull, as described in the previous section Online Registry Push and Pull, or from the Docker extension for VS Code.

Write a Docker Compose file for your application, as described in the Using Multiple Containers with TorizonCore or have one generated for you if using our IDE Extensions.

Deploy the update to the board as described in our Quickstart Guide.

If you want to deploy simultaneously the OS and application with Torizon Platform Services, you should use the synchronous update feature of our Torizon Platform, instead of bundling containers to a TorizonCore image.

You can learn more about container application updates with Torizon on our overview article

Private Registries and Torizon Platform​

If you decide to use a private container registry to host your images, make sure to follow the article Using Private Registries With Torizon Platform.



Send Feedback!