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

Using Private Registries With the Torizon Cloud

Introduction

This articles shows you how to use private registries to host your container application so it can be served to your devices during development, production and maintenance procedures. In this article, to achieve the goal of deploying private registry credentials to your devices, we'll leverage the flexibility of the TorizonCore Builder Tool and Torizon Remote Updates.

Why Use Private Registries

One of the most famous container registries - Docker Hub - allows people to host a single private container image and unlimited public containers with a free account. While this may be useful for quick evaluation and some proofs-of-concept, it may not be suitable for production, as you may need to protect your application's intellectual property. In those scenarios, a paid tier of Docker Hub, an alternative such as AWS, Azure container registries, or even a self-hosted registry would be suitable.

How it Works

It is straightforward to manually run a container hosted in a private registry, you will just need to authenticate to the registry. During production and maintenance procedures with Torizon OS, manually authenticating to your private Docker registry is not scalable, for that reason, it is recommended to deploy credentials to multiple devices.

With that, you will be able to use TorizonCore Builder Tool to Pre-provision Docker Containers onto a Torizon OS image, and Torizon Remote Updates to update your application.

Prerequisites

The following prerequisites are required to follow along with these instructions.

To install TorizonCore Builder, read our statements on OS and shell compatibility, then follow the instructions below, in order.

  1. Download the setup script into some writable directory in your system (here we use ~/tcbdir/):

    $ mkdir -p ~/tcbdir/ && cd ~/tcbdir/
    $ wget https://raw.githubusercontent.com/toradex/tcb-env-setup/master/tcb-env-setup.sh
    note

    If you did this before then you can skip this step unless you want to update the setup script. When you source the script (next step) it will show you a warning message if it determines an update is advisable.

  2. Source the script:

    $ cd ~/tcbdir/
    $ source tcb-env-setup.sh

    Make sure to do this from every shell instance that you intend to use with TorizonCore Builder. For advanced usage, run source tcb-env-setup.sh -h, or see the project README. The latter has information about using the early-access version of the tool for those interested.

    tip
    • Remember to source the setup script every time you start a new terminal (or shell instance).
    • The setup script installs a Bash completion script for TorizonCore Builder, making it possible to autocomplete commands and parameters by just pressing the TAB key.

    Beware that under Windows, you must pass extra parameters to the script when the use of the following commands is intended:

  3. Verify that the command torizoncore-builder is available:

    $ torizoncore-builder --help

Evaluation: Enabling a Single Device

This can be done in two cenarios:

  1. Pull images directly from a single device

If you want to pull/access a private registry outside of the context of Torizon remote updates then just perform a normal docker login.

  1. Pull images from a single device during updates with Torizon Cloud

For quick tests and development you can set up just a single device for private registry access. On your Torizon OS device enter the following command:

# sudo docker --config /etc/docker login

Once prompted, enter the username and password for your private registry.

If successful, this will create a config.json file in /etc/docker on the device. This file contains authentication information that is used by Docker if needed. Torizon OS and its updates features are configured so that any container update that is pushed to the device will look for the config.json file in this location, if needed.

Once you've entered the above command this specific device should be good to go. From the "Torizon Cloud Dashboard" you can schedule a container update for this device.

Fore more information on setting up a container update, take a look at the overview article. If you want to learn more, read the article Torizon Cloud Web Interface.

Development and Production: Enabling Multiple Devices

Later on in development or during early production you'll most likely be working with multiple devices. It would be very tedious to need to docker login, and add credentials to each device individually.

We'll resolve this by using the TorizonCore Builder Tool, and Torizon Remote Updates.

Creating a Custom Torizon OS Image With Docker Credentials

caution

Before continuing make sure you have TorizonCore Builder installed on your development machine, as pointed out in this article's Prerequisites section.

First, start with a single Torizon OS device and use docker login like before:

# sudo docker --config /etc/docker login

You are going to use TorizonCore Builder to capture these credentials and create a customized Torizon OS image. Since the config.json file is located in /etc we can easily isolate the changes and create a new image.

How to do this is described in the article Capturing Changes in the Configuration of a Board on Torizon OS.

To summarize the steps you'll need to follow from the article above:

  1. unpack a base Torizon OS Easy Installer image.
  2. isolate the config.json file in /etc/.
  3. union the changes to merge them onto the base image.
  4. deploy the changes to create a new Easy Installer image.

By the end of this process, you'll have a new Toradex Easy Installer that you can then flash to multiple boards. Any board you flash with this image will have the config.json file with your credentials information in /etc/docker.

Now you can push a container update to all of your boards and they should be able to access your private registry.

Using Torizon Cloud to Update the Credentials

It may be the case your devices are already deployed or you want to update the credentials on those devices. For this case, we will leverage Torizon Cloud.

First of all, go through all the steps in the previous section as they are all required here. Also, make sure you have your credentials.zip file from the "Torizon Cloud Dashboard" ready.

Once you have your custom Torizon OS image with Docker credentials, you can go ahead and push it to Torizon Cloud. Full details on the steps can be found in our article Signing and Pushing Torizon OS Images to Torizon Cloud.

To summarize the steps:

  1. Unpack a base Torizon OS Easy Installer image
  2. Isolate the config.json file in /etc/
  3. Union the changes to merge them onto the base image
  4. Push the changes to your Torizon Cloud account using your credentials.zip

As you can see the steps are very similar to the previous section. But, instead of a deploy as the last step, we instead push the changes to Torizon Cloud.

Once done you'll have a custom package on the "Torizon Cloud Dashboard" with your credentials baked in. Then, you must do the following:

  1. Update with your custom Torizon OS Package first. This will add/update the credentials to all your devices.
  2. Update with your custom container update. This will cause all of your devices to update their containers and access any private registry with your newly updated credentials if needed.


Send Feedback!