• NCSDK Documentation
• Overview
  • Introduction
  • Intel® Movidius™ Neural Compute Stick
• Installation
  • Basic Installation
  • Other Installation Options
    • Docker
    • virtualenv
    • Virtual Machine
• Frameworks
  • Network Configuration
  • Caffe
    • Overview
  • TensorFlow™
    • Overview
    • Compilation Guidance
    • Compiling TensorFlow-Slim Networks
    • Compiling Model Zoo Networks
• Toolkit
  • Toolkit Overview
  • mvNCCompile
  • mvNCCheck
  • mvNCProfile
• API
  • Overview
  • NCAPI v2
    • Python
    • C/C++
  • NCAPI v1
    • Python
    • C/C++
  • NCAPI v1 to NCAPI v2 Conversion
    • Python
    • C/C++
• Examples
• Release Notes
• Support

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.

Proxy Configuration

See Configuring Docker For Use With a Proxy.

sudo Configuration

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

The Docker run command creates a new container instance each time that is used. If you want to use your existing container, use the start command. (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.

$ exit

Other useful Docker commands

These commands are executed from your host terminal, not from inside the Docker container.

• View a list of Docker images:

docker images

• Remove an image (REPOSITORY_NAME can be found with the images command):

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 container ls command):

docker rm CONTAINER_NAME

• View a list of active Docker processes:

docker ps

• Stop an active Docker process (CONTAINER_ID can be found with the ps command):

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]]

Additional run options can be seen here. See the instructions above if you need to configure your Docker container to run behind a proxy.