Sign and Push Torizon Application Packages to Torizon Cloud

Introduction

The Torizon Cloud allows customers to push their own applications, defined as Docker Compose files, to the hosted service. It means that, after creating your application, you must sign and push it to Torizon Cloud before you can deploy it to your devices.

In this article, you learn how to use the TorizonCore Builder Tool for signing and pushing application packages to the Torizon Cloud. To push Torizon OS packages, see Sign and Push Torizon OS Packages to Torizon Cloud.

This article complies with the Typographic Conventions for Torizon Documentation.

Prerequisites

The prerequisites to complete these instructions are:

• A host machine with TorizonCore Builder installed.
• A credentials.zip file downloaded from your account on the Torizon Cloud dashboard.
• A Docker Compose file describing your application containers.

Make sure your working directory has the following structure, including credentials.zip and docker-compose.yml:

$ tree
.
├── credentials.zip
└── docker-compose.yml

Also make sure you can run TorizonCore Builder:

$ torizoncore-builder --help

Signing and pushing the Docker Compose file to Torizon Cloud

You can easily create application packages using the Torizon IDE Extension. For more information, see Build, Test, and Push Applications for Production.

The command platform push can also be used to push Docker Compose files to Torizon Cloud.

For this credentials.zip is also required along with the path to the Docker Compose file. Your compose file can have any name, as long as it ends in .yml, or .yaml. If it does not have either of these file endings then the command assumes you passed an OSTree reference instead.

$ torizoncore-builder platform push --credentials <credentials file> <path to docker-compose file>

There are also some additional arguments that can be passed to further customize this update package

$ torizoncore-builder platform push --credentials <credentials file> --package-name <name for this update> --package-version <version for this update> --canonicalize <path to docker-compose file>

The --package-name argument applies whatever is passed as the name for this updated package. Simply put, this is the name that your update appears under in the Torizon Cloud web UI. However, this argument is optional and, if not used, defaults to the pushed file's name.

The --package-version argument is the version that this package shows up as in the web UI. This doesn't have to be a numerical version and can be any legitimate string. This argument is also optional and, if not used, defaults to the date of upload at UTC time in the format of yyyy-mm-dd.

The --canonicalize argument generates a canonicalized version of the Docker Compose file, changing its extension to '.lock.yml' or '.lock.yaml' before pushing it to Torizon Cloud. If no other package name is provided, using the --package-name argument, the default package name is the generated file's name when using the canonicalize argument.

info

For a Docker Compose file to be suitable for use with offline updates it must be in canonical form.

Moreover, due to some known limitations, the package name must only employ basic ASCII characters excluding control ones and those in the set \/:*?"><|, otherwise the Lockbox generation may fail later.

For example running the following command:

$ torizoncore-builder platform push --credentials credentials.zip --package-name tcb-test --package-version 1.1 docker-compose.yml

This results in the following appearing in your account's web UI:

Lockfiles and Canonical Docker Compose Files

The platform push command with the --canonicalize-only option generates a canonical copy of the used Docker Compose file, but not push it to the platform.

$ torizoncore-builder platform push --canonicalize-only <docker-compose file>

info

Canonicalizing a Docker Compose file basically means putting it into a specific YAML format, removing comments (lines starting with a # or any word included after a # character), and associating HASH values to Docker images.

The canonical Docker Compose file makes it easier to track changes to this Docker Compose file and also make your deployment more secure since it pulls down images based on HASHES instead of tags.

When pushing a Docker Compose file to Torizon Cloud, using the --canonicalize option, TorizonCore Builder:

• Canonicalize the Docker Compose file.
• Save a copy of the canonicalized Docker Compose file with .lock.yml or .lock.yaml extension (depending on how you named your Docker Compose file).
• Send the canonicalized Docker Compose file to Torizon Cloud.

Setting Package Compatibility on Application Packages

Setting package compatibilities can be done on application packages within the Torizon Cloud system. Doing this specifies a set of OS package versions, identified by their unique hash value, that the application should be installed into. This can be useful when, as an example, your application depends on a specific kernel version. This could be due to driver capability that only exists in the newer kernel or any other features. Adding this compatibility setting into the package allows the Torizon platform to warn operators when they are deploying applications to a version of the OS that may not work.

info

The OS package Hash can be found by inspecting the OS package on your Platform account. The OS package must be accessible on your Platform account.

Defining compatibilities can be done both through the Torizon web UI and using the command line tooling.

Setting Package Compatibility from the Command Line

When pushing a Docker Compose file to Torizon Cloud, you can set the package compatibility using the --compatible-with argument. This argument accepts the OS package hash and restricts an application package so it can only be installed with a compatible OS package.

$ torizoncore-builder platform push --compatible-with sha256=<OS package hash> --credentials <credentials file> <path to docker-compose file>

Setting Package Compatibility from the Web interface

Once the Docker Compose file is added to your Platform account, you can inspect its compatibilities in the compatibilities section when clicking on the Docker Compose Package.

To edit the Package compatibility on a Docker Compose file in the platform, use the Configure Compatibilities section: