Installation and Configuration with Docker
Docker is an open-source platform for the creation of lightweight operating-system-level virtualizations called containers for building, distributing, and running applications. Docker images are packages that include everything needed to run the container and its applications, and Docker containers are runtime instances of these images. You can read more about basic Docker concepts here.
The Intel® Movidius™ Neural Compute SDK (Intel® Movidius™ NCSDK) can be installed and run within a Docker container so that its required packages and libraries are isolated from the rest of your system.
This document will tell you how to use the NCSDK with Docker. These instructions assume that you will be using a neural compute device that is connected to your host machine via USB.
Install Docker on an Ubuntu host
Go to https://docs.docker.com/install/linux/docker-ce/ubuntu/ and follow the instructions to install docker-ce on Ubuntu.
To use Docker in Ubuntu without having to use sudo, execute the following commands:
sudo groupadd docker sudo usermod -aG docker $USER
Reboot your machine for this to take effect.
Other Operating Systems
These instructions have been validated in Docker Community Edition for Ubuntu. Other versions of Docker may not have the required USB support.
These instructions can be done in an Ubuntu virtual machine.
Non-privileged Docker Containers
Versions of the NCSDK prior to 2.08 required that the docker run command was issued with the –privileged flag. This is due to the way the NCS device boots and loads its firmware. If you are OK with running your docker container with the –privileged flag you can skip this section and follow the instructions in the Privileged Docker Containers section below. If you want to run as docker in a non-privileged container then follow the instructions in this section.
There are a few concepts to be aware of when using NCS devices in a non-privileged docker container. In this mode the NCAPI libraries within the docker container must be rebuilt with NO_BOOT=yes NO_RESET=yes flags to prevent the API from rebooting/resetting the NCS devices. The provide docker_cmd.sh script takes care of this for you. Also, since the API isn’t booting the devices and loading the firmware this must be done prior to running an application that uses the devices and prior to starting the docker container. There is a seperate program provided that does this called ncs_boot_devices. When starting the docker container the USB device name must be passed to the container with the –device flag. The device name is not static, it changes over time so the docker_cmd.sh script also handles this.
To make it easier to navigate the concepts above the following instructions can be followed.
1. Create a Docker Image for the NCSDK to run in Non-privileged Mode
The provided docker file Dockerfile_NoPreviligeAccess will be used create a docker image named ‘ncsdk’ when you follow the commands below. You must have already cloned the ncsdk repository and should be in the top level directory named ncsdk. Note if you want to use a specific branch of the repository be sure to do git checkout for the desired branch. After these commands are successfully executed, the docker image will contain the ncsdk and the NCAPI will have been compiled with the appropriate flags (NO_BOOT=yes and NO_RESET=yes.) within the image.
$ cd <NCSDK installation directory> $ docker build -t ncsdk -f ./extras/docker/Dockerfile_NoPreviligeAccess .
2. Prepare NCS Devices for Use Within the Non-privileged Container
Run the following commands to build and run the ncs_boot_devices program which loads the device firmware.
$cd <NCSDK installation path>/extras/docker/ncs_boot_devices $ #The path to api src directory is typically "../../../api/src" $ export MVNC_API_PATH=<path to api src > $ make ncs_boot_devices $ #Make sure all NCS devices are plugged into the host system at this point $ #Run the program to boot the devices and load the firmware $ make run
3. Run the Non-privileged Docker Container.
The provided docker_cmd.sh script will run the docker container for you with appropriate –device parameters.
$ #Now the devices in the system have been booted with correct firmware. $ #Start the docker container with correct --device parameters $ cd <NCSDK installation path>/extras/docker $ ./docker_cmd.sh
Privileged Docker Containers
The simplest way to use the NCS within a docker container is to do it from a container thats running with the –privileged flag. This is not always desirable however, so if you would rather run in a non-privileged container see the Non-privileged Docker Containers section above.
1. Create a Docker Image for the NCSDK to Run in Privileged Mode
We have provided a Dockerfile to build an Ubuntu-based Docker image that has the NCSDK installed. This command will create an image named ‘ncsdk’. You must have already cloned the ncsdk repository and should be in the top level directory named ncsdk. Note if you want to use a specific branch of the repository be sure to do git checkout for the desired branch.
$ cd <NCSDK installation directory> $ docker build -t ncsdk -f ./extras/docker/Dockerfile .
2. Create and Run a Privileged Docker container from the Built Image
This command will create a container named ‘ncsdk’.
$ docker run --net=host --privileged -v /dev:/dev --name ncsdk -i -t ncsdk /bin/bash
The elevated permissions required via –privileged are necessary for the USB access required by the neural compute device unless following the non-privileged instructions above.
Use your NCSDK container
Starting the container
run command creates a new container instance each time that is used. If you want to use your existing container, use the
(Note: The container is named ‘ncsdk’ when following both the privileged and non-privileged instructions above.)
docker start -a -i ncsdk
Build NCSDK examples (optional)
You must have a neural compute device connected to a USB port in your host system when running this command. This command is executed inside of your Docker container.
$ make examples
Exit the container
This command is executed inside of your Docker container.
Other useful Docker commands
These commands are executed from your host terminal, not from inside the Docker container.
- View a list of Docker images:
- Remove an image (REPOSITORY_NAME can be found with the
docker rmi REPOSITORY_NAME
- View a list of all Docker containers:
docker container ls -a
- Remove a Docker container (CONTAINER_NAME can be found with the
docker rm CONTAINER_NAME
- View a list of active Docker processes:
- Stop an active Docker process (CONTAINER_ID can be found with the
docker stop CONTAINER_ID
- Create a Docker image from a container:
Commit the image (CONTAINER_NAME can be found with the
container ls command; REPOSITORY_NAME can be any name for the image).
docker commit CONTAINER_ID [REPOSITORY_NAME[:TAG]]
run options can be seen here. See the instructions above if you need to configure your Docker container to run behind a proxy.