Search by Tags

OSTree Easy Installer Builder


Article updated at 24 Jul 2019
Subscribe for this article updates

Warning: the Torizon Update System is a project currently under development at Toradex Labs. It is still an experimental project in it's early stages which is subject to changes without notice. This might impact new releases and/or iterations.


OSTree Easy Installer Builder is a tool provided by Toradex for the Torizon platform. This tool can be used to add files to a Torizon base root file system and generate an image that can then be installed using Toradex Easy Installer. The tool, running on your development machine, will download a Torizon root filesystem via ostree and merge it with the contents of a local directory.

This article complies to the Typographic Conventions for Torizon Documentation.


How Does it Work

Files in the local directory will be added to the root filesystem of Torizon. For example, if you have a folder with this structure:

$ tree fs
├── dummydir1
│   └── dummydir2
│       └── dummyfile2
└── dummyfile1

2 directories, 2 files

And pass the fs directory to the tool as root folder, in your final image you will have dummydir1 and dummyfile1 under the root directory of the target file system:

# ls / -la
total 36
drwxr-xr-x   13 root     root          4096 Feb 22 14:38 .
drwxr-xr-x   13 root     root          4096 Feb 22 14:38 ..
lrwxrwxrwx    1 root     root             7 Feb 22 14:37 bin -> usr/bin
drwxr-xr-x    4 root     root          4096 Feb 22 14:38 boot
drwxr-xr-x   13 root     root         14440 Feb 22 14:48 dev
drwxrwxr-x    3 root     root          4096 Jan  1  1970 dummydir1
-rw-rw-r--    2 root     root             7 Jan  1  1970 dummyfile1
drwxr-xr-x   32 root     root          4096 Feb 22 14:48 etc
lrwxrwxrwx    1 root     root            17 Feb 22 14:37 home -> var/rootdirs/home
lrwxrwxrwx    1 root     root             7 Feb 22 14:37 lib -> usr/lib
lrwxrwxrwx    1 root     root            18 Feb 22 14:37 media -> var/rootdirs/media
lrwxrwxrwx    1 root     root            16 Feb 22 14:37 mnt -> var/rootdirs/mnt
lrwxrwxrwx    1 root     root            14 Feb 22 14:37 ostree -> sysroot/ostree
dr-xr-xr-x   96 root     root             0 Jan  1  1970 proc
drwxrwxrwt   14 root     root           400 Feb 22 14:51 run
lrwxrwxrwx    1 root     root             8 Feb 22 14:37 sbin -> usr/sbin
dr-xr-xr-x   12 root     root             0 Feb 22 14:48 sys
drwxr-xr-x   12 root     root          4096 Feb 22 14:38 sysroot
drwxrwxrwt   10 root     root           200 Feb 22 14:49 tmp
drwxr-xr-x   13 root     root          4096 Jan  1  1970 usr
drwxr-xr-x    8 root     root          4096 Feb 22 14:48 var

To install the Toradex Easy Installer image that contains the updated root file system you'll have to run the Toradex Easy Installer on your module, copy the folder generated by the tool on some removable media (SD, USB stick) and insert the media in the target device.

How to Use the OSTree Easy Installer Builder

The tools needs to know module type, the source OSTree repository, the branch you want to use for your image and accepts a folder with the additional contents and a target folder where an easy installer image will be generated. Starting the container with no additional arguments on your development PC will show a help message:

$ docker run --rm -it torizon/ostree-easy-installer-builder
Usage: easyinstallerbuilder [options] module remote branch folder outputfolder
        module: module type, can be one of the following:
        repo: ostree remote (ex:
        branch: branch that should be taken from remote (ex: torizon/torizon-core-docker)
        folder: folder containing files to be added to image
        outputfolder: folder where Easy Installer image will be created
        -b, --baseversion: version of base image, if no version is specified the last one from easy installer feed will be used
        -v, --verbose: generate more verbose output about performed operations

You can pass arguments to the docker command line but, since the tool need to access local filesystem to collect the files that should be added to the image and to generate the output image, you'll have to provide mountpoints using -v option of docker.

$ docker run -it --rm -v $(pwd)/fs:/builder/fs -v $(pwd)/output:/builder/output torizon/ostree-easy-installer-builder:latest easyinstallerbuilder -v colibri-imx6 torizon/torizon-core-lite /builder/fs /builder/output

The command line above, for example, will generate an image for colibri-imx6, using the nightly feed and the core-lite image. Additional content will be taken from a subfolder named "fs" in current directory and the image will be generated in the output subfolder. As you can see $(pwd)/fs and $(pwd)/output folders are mounted using the -v argument of docker run and their mountpoints (/builder/fs and /builder/output) are passed as arguments.

Contents of output folder will be erased by the tool.

Your PC has to be connected to the internet when running the tool because base easy installer image and ostree contents are downloaded at runtime.
Build may take some minutes because content is downloaded via network. This is the output generated during build (verbose option has been selected):

$ docker run -it --rm -v $(pwd)/fs:/builder/fs -v $(pwd)/output:/builder/output torizon/ostree-easy-installer-builder:latest easyinstallerbuilder -v colibri-imx6 torizon/torizon-core-lite /builder/fs /builder/output

Retrieving image for module colibri-imx6...
Downloading image 20190218095839/torizon-core-lite-colibri-imx6-20190218113510-Tezi_0.3a1.115...
Parsing configuration file image.json...
Downloading image.json
Downloading uEnv.txt
Downloading marketing.tar
Downloading toradexlinux.png
Downloading torizon-core-lite-colibri-imx6-20190218113510.bootfs.tar.xz
Downloading torizon-core-lite-colibri-imx6-20190218113510.rootfs.ota.tar.xz
Downloading SPL
Downloading u-boot.imx
Cloning base root filesystem for colibri-imx6 in work/rootfs...
Root filesystem found as torizon-core-lite-colibri-imx6-20190218113510.rootfs.ota.tar.xz.
Extracting archive...
Removing ostree deployments...
Saving device trees...
Device tree source folder work/rootfs/boot/ostree/torizon-59ca951f2f71e7817987f57a7a074c2c188a66a29a1e466d1135c13f54407827
saving device tree devicetree-imx6dl-colibri-eval-v3.dtb
Removing boot folder...
Merging changes...
Pulling remote torizon/torizon-core-lite
Pull: 361295 bytes transferred.
Pull: 681282 bytes transferred.
Pull: 1041522 bytes transferred.
Pull: 1369621 bytes transferred.
Pull: 30347705 bytes transferred.
Pull: 30550389 bytes transferred.
Committing changes from /builder/fs to changes
Transaction committed. 14 bytes 2 objects written.
Merging remote torizon/torizon-core-lite - commit 32c45ac7801d3fa6d1d353ea252cf7dc51fb1a57411e8b882883956bf6223ebf...
Checking out tree to merge...
Merging local changes - commit 92f6e691ded93dc857db39fc99f3460a78d65e1e66a526980b9e5971ecb3cbb0...
Merging into merge...
Committing changes from merge to merged
Transaction committed. 546526 bytes 18 objects written.
Commit f1cd3dd615c7db54755c16ccf551d96f65ebb3755206427709acc7da993d2b4c has been generated.
Merging deployment for torizon - revision f1cd3dd615c7db54755c16ccf551d96f65ebb3755206427709acc7da993d2b4c - commit f1cd3dd615c7db54755c16ccf551d96f65ebb3755206427709acc7da993d2b4c...
Deploying tree...
Freed objects: 47.7 MB
Restoring dtbs...
Creating /var entries...
Copying easy installer base image to /builder/output...
Updating image configuration file /builder/output/image.json...
Generating root filesystem archive /builder/output/20190222-rootfs.ota.xz...