The Torizon Platform Services allows customers to push their own customized versions of TorizonCore (OS updates) and Docker Compose (application updates) to our hosted service. It means that, after customizing an image or creating your application, you must sign and push it to Torizon Platform Services.
In this article, you will learn how to use the TorizonCore Builder Tool for signing and pushing packages to the Torizon Platform Services.
This is a feature available on prime-tiers of the Torizon Platform Services. If you want to learn more about the Torizon Platform Services pricing and plans, please contact us.
Request access to evaluate the Torizon Platform Services premium features |
This article complies to the Typographic Conventions for Torizon Documentation.
The prerequisites to complete these instructions are:
.tar
file containing the TorizonCore Image with no-container pre-provisioned for offline installation.credentials.zip
file downloaded from your account on the Torizon Platform dashboard.splash.png
, like this one (Obs.: the splash screen image needs to be a png file with a maximum size of your screens resolution - typically a resolution around 600x400 is used).Make sure your working directory has the following structure, including credentials.zip
, splash.png
, docker-compose.yml
, and a directory called image
containing the uncompressed TorizonCore installation image:
$ tree
.
├── credentials.zip
├── image
│ ├── image.json
│ ├── marketing.tar
│ ├── prepare.sh
│ ├── SPL
│ ├── toradexlinux.png
│ ├── torizon-core-docker-apalis-imx6.ota.tar.zst
│ ├── u-boot.img
│ ├── u-boot-initial-env-spl
│ └── wrapup.sh
└── splash.png
└── docker-compose.yml
Also make sure you can run TorizonCore Builder:
$ torizoncore-builder --help
Let's modify a TorizonCore image. In this example, we will apply a custom splash screen to illustrate the process.
Warning: When generating TorizonCore images for updates you should not bundle application containers into the image. Also, if your update package is intended to be used with offline updates, remember to capture the proper configuration of Aktualizr for using with offline updates into your TorizonCore image.
To install TorizonCore Builder, read our statements on OS and shell compatibility, then follow the instructions below, in order.
Create and enter a working directory where your customization will be stored:
$ mkdir ~/tcbworkdir
$ cd ~/tcbworkdir
Use the setup script named tcb-env-setup.sh, available on the Toradex Github, to setup TorizonCore Builder:
$ wget https://raw.githubusercontent.com/toradex/tcb-env-setup/master/tcb-env-setup.sh
$ source tcb-env-setup.sh
For advanced usage, run source tcb-env-setup.sh -h
, or see the project README.
If using Windows, you must pass extra parameters to the script when using the following commands:
ostree serve
: consult the ostree serve reference.Tip: 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.
Verify that the command torizoncore-builder
is available:
$ torizoncore-builder --help
Warning: Make sure to: (1) source the script, (2) every time you open a new terminal, (3) inside the working directory you have previously created. Otherwise, it will not work as intended and, most importantly, the torizoncore-builder
alias will not be created properly.
Apply the custom splash screen image – when using torizoncore-builder versions 3.0.0 or later:
torizoncore-builder splash splash.png
Or, if using versions of the tool before 3.0.0:
torizoncore-builder splash --image splash.png
Now create a new TorizonCore OSTree image – when using torizoncore-builder versions 3.0.0 or later:
torizoncore-builder union my-custom-image
Or, if using versions of the tool before 3.0.0:
torizoncore-builder union --union-branch my-custom-image
Note: For a more detailed description of splash
, union
and other TorizonCore Builder commands, see TorizonCore Builder Tool article.
The command platform push
from TorizonCore Builder can be used to push a new TorizonCore image to Torizon Platform.
The command requires the credentials.zip
file from Torizon Platform and a reference to the OSTree repository that should be pushed to the Torizon Platform server.
torizoncore-builder platform push --credentials <credentials file> <ostree reference>
In our example, the OSTree reference is called my-custom-image
(defined in the union
command above), so the command below will push the customized image to Torizon Platform:
torizoncore-builder platform push --credentials credentials.zip my-custom-image
Now, if you log in to Torizon Platform Web Interface and initiate an update, you should see the customized image, ready to be used to update a device:
And, if everything went fine with the update, you shall see your board rebooting when the process is completed, and the splash screen shown in the device initialization will be the one defined in the new image.
There are also some additional arguments that can be passed to further customize this image update package.
torizoncore-builder platform push --credentials <credentials file> --package-name <name for this image update> --package-version <version for this image update> <ostree reference> --hardwareid <supported hardware for this image update>
The --package-name
argument will apply whatever is passed as the name for this image update package. Simply put, this is the name that your update will appear under in our Torizon Platform Web UI. However, this argument is optional and, if not used, will default to the OSTree reference
.
The --package-version
argument is the version that this image update package will show up as in the web UI. This doesn't have to be a numerical version and can be any legitimate string. This argument is optional, and if not used, the version will default to the OSTree subject
.
The --hardwareid
argument defines which hardware IDs the image to be uploaded will be compatible with. This argument can be repeated multiple times, adding extra supported hardware IDs to the image. It's important to notice this argument will override the default image's hardware ID. Under the Supported Hardware
tab at the Torizon Platform Web UI, you can confirm the changes. This argument is optional, and if not used, the supported hardware ID will default to the original image's hardware ID.
The command platform push
can also be used to push docker-compose files to Torizon Platform.
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 will assume 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 will apply whatever is passed as the name for this updated package. Simply put, this is the name that your update will appear under in our Torizon Platform Web UI. However, this argument is optional and, if not used, will default to the pushed file's name.
The --package-version
argument is the version that this package will show 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, will default 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 Platform. If no other package name is provided, using the --package-name
argument, the default package name will be the generated file's name when using the canonicalize argument.
Note: For a docker-compose file to be suitable for use with offline-updates it must be in canonical form.
For example running the following command:
torizoncore-builder platform push --credentials credentials.zip --package-name tcb-test --package-version 1.1 docker-compose.yml
Will result in the following appearing in your account's web UI:
When pushing a docker-compose file to Torizon Platform, TorizonCore Builder will:
.lock.yml
or .lock.yaml
extension (depending on how you named your docker-compose file)--canonicalize
option was provided, send the canonicalized docker-compose file to Torizon Platform.Note: 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.
This way, it would be easier to track changes to this docker-compose file and also make your deployment more secure since we are pulling down images based on HASHES instead of tags.