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

How to Store Docker Data on an External Storage Device (USB/SD Card)

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.

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

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

This article complies with the Typographic Conventions for Torizon Documentation.

Intended Audience and Caveats​

danger

think carefully if you really need to use this feature, since it limits the overall experience with Torizon OS.

  • This feature was added specifically to address the storage requirements of resource-limited devices like Colibri iMX6ULL or Colibri iMX7.
  • 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 Cloud.

Prerequisites​

The prerequisites to complete these instructions are:

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.

info

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
caution

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 Torizon OS image for production, see the Capturing Changes in the Configuration of a Board on Torizon OS article.

A limitation of using the external media is that it is not possible to Pre-provision Docker Containers onto a Torizon OS 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 Cloud.



Send Feedback!