How to Store Docker Data on an External Storage Device (USB/SD Card)
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 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
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, 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 Cloud.
The prerequisites to complete these instructions are:
- A module running Torizon OS
- 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.
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):
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
# ls -l /media/
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: 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/
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
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.