Docker Environment#

Docker is a set of “platform as a service” products that uses the OS-level virtualization to deliver software in packages called containers. Docker container provides a quick start environment to the developer to run the out of box demos and build applications.

The Docker image is based on Ubuntu 20.04.LTS and contains different open source components like OpenCV, GStreamer, Python and pip packages which are required to run the demos. The user can choose to install any additional 3rd party applications and packages as required.

Building Docker image#

The docker/Dockerfile in the edge_ai_apps repo describes the recipe for creating the Docker container image. Feel free to review and update it to include additional packages before building the image.

Note

Building Docker image on target using the provided Dockerfile will take about 15-20 minutes to complete with good internet connection. Building Docker containers on target can be slow and resource constrained. The Dockerfile provided will build on target without any issues but if you add more packages or build components from source, running out of memory can be a common problem. As an alternative we highly recommend trying QEMU builds for cross-compiling the images for arm64 architecture on a PC and then load the compiled image on target.

Initiate the Docker image build as shown,

debian@beaglebone:/opt/edge_ai_apps/docker#./docker_build.sh

Running the Docker container#

Enter the Docker session as shown,

debian@beaglebone:/opt/edge_ai_apps/docker#./docker_run.sh

This will start a Ubuntu 20.04.LTS image based Docker container and the prompt will change as below,

[docker] debian@beaglebone:/opt/edge_ai_apps#

The Docker container has been created in privilege mode, so that it has root capabilities to all devices on the target system like Network etc. The container file system also mounts the target file system of /dev, /opt to access camera, display and other hardware accelerators the SoC has to offer.

Note

It is highly recommended to use the docker_run.sh script to launch the Docker container because this script will take care of saving any changes made to the filesystem. This will make sure that any modifications to the Docker filesystem including new package installation, updates to some files and also command history is saved automatically and is available the next time you launch the container. The container will be committed only if you exit from the container explicitly. If you restart the board without exiting container, any changes done from last saved state will be lost.

Note

After building and running the docker container, one needs to run setup_script.sh before running any of the demo applications. Please refer to Software setup for more details.

Handling proxy settings#

If the board running the Docker container is behind a proxy server, the default settings for downloading files and installing packages via apt-get will not work. If you are running the board from TI network, docker build and run scripts will automatically detect and configure necessary proxy settings

For other cases, you need to modify the script /usr/bin/setup_proxy.sh to add the custom proxy settings required for your network.

Additional Docker commands#

Note

This section is provided only for additional reference and not required to run out-of-box demos

Commit Docker container

Generally, containers have a short life cycle. If the container has any local changes it is good to save the changes on top of the existing Docker image. When re-running the Docker image, the local changes can be restored.

Following commands show how to save the changes made to the last container. Note that this is already done automatically by docker_run.sh when you exit the container.

cont_id=`docker ps -q -l`
docker commit $cont_id edge_ai_kit
docker container rm $cont_id

For more information refer: Commit Docker image

Save Docker Image

Docker image can be saved as tar file by using the command below:

docker save --output <pre_built_docker_image.tar>

For more information refer here. Save Docker image

Load Docker image

Load a previously saved Docker image using the command below:

docker load --input <pre_built_docker_image.tar>

For more information refer here. Load Docker image

Remove Docker image

Docker image can be removed by using the command below:

Remove selected image:
docker rmi <image_name/ID>

Remove all image:
docker image prune -a

For more information refer rmi reference and Image prune reference

Remove Docker container

Docker container can be removed by using the command below:

Remove selected container:
docker rm <container_ID>

Remove all container:
docker container prune

For more information refer here. rm reference and Container Prune reference

Relocating Docker Root Location#

The default location for Docker files is /var/lib/docker. Any Docker images created will be stored here. This will be a problem anytime the SD card is updated with a new targetfs. If a secondary storage (SSD or USB based storage) is available, then it is recommended to relocate the default Docker root location so as to preserve any existing Docker images. Once the relocation has been done, the Docker content will not be affected by any future targetfs updates or accidental corruptions of the SD card.

The following steps outline the process for Docker root directory relocation assuming that the current Docker root is not at the desired location. If the current location is the desired location then exit this procedure.

  1. Run ‘Docker info’ command inspect the output. Locate the line with content Docker Root Dir. It will list the current location.

  2. To preserve any existing images, export them to .tar files for importing later into the new location.

  3. Inspect the content under /etc/docker to see if there is a file by name daemon.json. If the file is not present then create /etc/docker/docker.json and add the following content. Update the ‘key:value’ pair for the key “graph” to reflect the desired root location. If the file already exists, then make sure that the line with “graph” exists in the file and points to the desired target location.

{
  "graph": "/run/images/nvme0n1/docker_root",
  "storage-driver": "overlay",
  "live-restore": true
}

In the configuration above, the key/value pair ‘“graph”: “/run/images/nvme0n1/docker_root”’ defines the root location ‘/run/images/nvme0n1/docker_root’.

  1. Once the daemon.json file has been copied and updated, run the following commands

$ systemctl restart docker
$ docker info

Make sure that the new Docker root appears under Docker Root Dir value.

  1. If you exported the existing images in step (2) then import them and they will appear under the new Docker root.

  2. Anytime the SD card is updated with a new targetfs, steps (1), (3), and (4) need to be followed.

Additional references