Pulling A Container

Before you using a container from the NGC container registry, review the prerequisites described in the previous chapter.

You must also have access and logged into the NGC container registry as explained in the NGC Getting Started Guide.

Key Concepts

In order to issue the pull and run commands, ensure that you are familiar with the following concepts.

A pull command looks similar to:
docker pull nvcr.io/nvidia/caffe2:17.10
A run command looks similar to:
docker run --gpus all -it --rm –v local_dir:container_dir nvcr.io/nvidia/caffe2:<xx.xx>
Note: The base command docker run --gpu all assumes that your system has Docker 19.03-CE installed. See the section Enabling GPU Support for NGC Containers for the command to use for earlier versions of Docker.
The following concepts describe the separate attributes that make up the both commands.
nvcr.io
The name of the container registry, which for the NGC container registry and the NVIDIA DGX container registry is nvcr.io.
nvidia
The name of the space within the registry that contains the container. For containers provided by NVIDIA, the registry space is nvidia. For more information, see NGC Container Registry Spaces.
-it
You want to run the container in interactive mode.
--rm
You want to delete the container when finished.
–v
You want to mount the directory.
local_dir
The directory or file from your host system (absolute path) that you want to access from inside your container. For example, the local_dir in the following path is /home/jsmith/data/mnist.
-v /home/jsmith/data/mnist:/data/mnist

If you are inside the container, for example, using the command ls /data/mnist, you will see the same files as if you issued the ls /home/jsmith/data/mnist command from outside the container.

container_dir
The target directory when you are inside your container. For example, /data/mnist is the target directory in the example:
 -v /home/jsmith/data/mnist:/data/mnist
<xx.xx>
The tag. For example, 17.10.

Accessing And Pulling From The NGC container registry

You can access the NGC container registry by running a Docker commands from any Linux computer with Internet access on which Docker is installed.You can access the NGC container registry at nvcr.io through the Docker CLI.

Before accessing the NGC container registry, see NGC Getting Started Guide for instructions on how to access the website and, if you intend to access locked NGC content, know how to sign up for an NGC account and obtain an API key.

Logging in to the NGC container registry

Before accessing locked NGC content, you must sign up for an NGC account and obtain an API key as explained in the NGC Getting Started Guide. Then log in to the NGC registry from the command line as follows.
  1. Log in to the NGC container registry.
    $ docker login nvcr.io
  2. When prompted for your user name, enter the following text:
    $oauthtoken
  3. The $oauthtoken username is a special user name that indicates that you will authenticate with an API key and not a username and password.
  4. When prompted for your password, enter your NGC API key as shown in the following example.
    Username: $oauthtoken
    Password: k7cqFTUvKKdiwGsPnWnyQFYGnlAlsCIRmlP67Qxa
    Tip: When you get your API key, copy it to the clipboard so that you can paste the API key into the command shell when you are prompted for your password.

Pulling A Container From The NGC container registry Using The Docker CLI

You can browse the available containers in the NGC container registry by opening the NGC website using a web browser

  1. Pull the container that you want from the registry. For example, to pull the NAMD container:
    $ docker pull nvcr.io/hpc/namd:2.13
    
    You can copy the correct pull command for a specific NGC container by browsing the NGC website, selecting an NGC container, then clicking the download icon. Paste the command into the command line. See the NGC Getting Started Guide for details on using the NGC website.
  2. List the Docker images on your system to confirm that the container was pulled.
    $ docker images
    For more information pertaining to your specific container, refer to the /workspace/README.md file inside the container.
After pulling a container, you can run jobs in the container to run scientific workloads, train neural networks, deploy deep learning models, or perform AI analytics.