Torizon 5.0.0

Introduction

Docker generates a lot of data that increases storage usage, and sometimes this is a problem for resource-limited devices like Colibri iMX6ULL or Colibri iMX7, which are both equipped with raw NAND flash and therefore are experimental Torizon releases. If you, nonetheless, want to use one of those experimental releases, please contact us to learn more about it.

You can, of course, use this article on any other Toradex SoM that is supported by Torizon. It's just rarely required, as those have eMMC flash storage with at least 4GB space, which is likely to be enough for your application.

This article will explain how to extend the storage in TorizonCore, storing Docker data on an external device like an SD Card or a USB stick.

This article complies to the Typographic Conventions for Torizon Documentation.

Intended Audience and Caveats

Attention: think carefully if you really need to use this feature, since it limits the overall experience with TorizonCore.

• This feature was added specifically to address the storage requirements of resource-limited devices like Colibri iMX6ULL or Colibri iMX7, which are both equipped with raw NAND flash and therefore are experimental Torizon releases.
• After the module is configured and running, make sure to not remove the external storage device at runtime, or you may lose data or even corrupt the device partition.
• Be aware of the security implications of having all your application(s) and data stored on a removable device. Anyone with physical access to your product will be able to easily remove the external storage device and dump its content.
• When you use this feature, you may lose the ability to use some features from the TorizonCore Builder Tool and Torizon OTA.

Prerequisites

The prerequisites to complete these instructions are:

• A module running TorizonCore
• A serial console or networking connection (SSH) to the module
• An external storage device like an SD Card or a USB stick

Preparing the External Storage Device

The first step is to format the storage device with an ext4 partition labeled docker (it is important to set the label of the partition using exactly the name docker, or the procedures in this article won't work).

Optionally, you can also create a second partition labeled userdata (also formatted with ext4). In your application, you can use this partition to store applications' data.

Note: Make sure to use a high-quality external storage device, or you may suffer from performance issues or even data corruption.

In the end, the storage device will have the following partition layout (the docker partition is mandatory and the userdata is optional):

• 

  External Storage Partition Layout

Enabling the Usage of the External Storage Device

Insert the external storage device in the carrier board and reboot.

Open a terminal connected to the module and confirm that both partitions were automatically mounted at /media:

# ls -l /media/
total 8
drwx--x--x 15 root root 4096 Jan 28 07:37 docker
drwxr-xr-x  2 root root 4096 Jan 28 11:29 userdata

Now run the following command to configure the usage of /media/docker to store Docker data:

# sudo sh -c "echo 'export DOCKER_ON_EXTERNAL_STORAGE=1' > /etc/profile.d/docker.sh"

Reboot the module:

# sudo reboot

In the next boot, Docker will automatically start using the external storage device to store data.

You can check the logs to confirm that the configuration was successful:

# journalctl -u usermount.service | grep "Docker dataroot directory successfully mounted"
Jan 28 07:37:30 apalis-imx6-05039068 usermount-mounter[647]: Docker dataroot directory successfully mounted at /media/docker.

You can also list the content of /media/docker to make sure Docker is using the external storage device partition:

# sudo ls -l /media/docker/
Password: 
total 52
drwx------  2 root root 4096 Jan 28 11:35 builder
drwx--x--x  4 root root 4096 Jan 28 11:35 buildkit
drwx------  3 root root 4096 Jan 28 11:35 containerd
drwx------  2 root root 4096 Jan 28 11:39 containers
drwx------  3 root root 4096 Jan 28 11:35 image
drwxr-x---  3 root root 4096 Jan 28 11:35 network
drwx------ 13 root root 4096 Jan 28 16:01 overlay2
drwx------  4 root root 4096 Jan 28 11:35 plugins
drwx------  2 root root 4096 Jan 28 07:37 runtimes
drwx------  2 root root 4096 Jan 28 11:35 swarm
drwx------  2 root root 4096 Jan 28 16:01 tmp
drwx------  2 root root 4096 Jan 28 11:35 trust
drwx------  2 root root 4096 Jan 28 11:35 volumes

Warning: If you enable this feature but doesn't connect an external storage device, the Docker service will fail to start. This will prevent Docker from inadvertently using the internal storage device.

Preparing an Image for Production

To commit the configuration changes on the /etc directory to a TorizonCore image for production, see the Capturing Changes in the Configuration of a Board on TorizonCore article.

A limitation of using the external media is that it is not possible to Pre-provision Docker Containers onto a TorizonCore image. After flashing the image into the SoM, you have to install the containers on the first boot. You can do it several ways, one of them is through Torizon OTA.