Pulling A Container

Before you can pull a container from the NGC container registry, you must have Docker and nvidia-docker installed. For DGX users is is explained in Preparing to use NVIDIA Containers Getting Started Guide.

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:
nvidia-docker run -it --rm –v local_dir:container_dir nvcr.io/nvidia/caffe2:<xx.xx>
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

This section is appropriate if you are using via a cloud provider.

If you are accessing the NVIDIA containers from a Cloud Server Provider such as Amazon Web Services (AWS), then you should first create an account at the NGC container registry located at https://ngc.nvidia.com. After you create an account, the commands to pull containers are the same as if you had a DGX-1 in your own data center. However, currently, you cannot save any containers to the NGC container registry. Instead you have to save the containers to your own Docker repository that is either on-premise or in the Cloud.

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

Before accessing the NGC container registry, ensure that the following prerequisites are met. For more information about meeting these requirements, see NGC Getting Started Guide.
  • Your account is activated.
  • You have an API key for authenticating your access to the NGC container registry.
  • You are logged in to your client computer with the privileges required to run nvidia-docker containers.
After your account is activated, you can access the NGC container registry from one of two ways:
A Docker registry is the service that stores Docker images. The service can be on the internet, on the company intranet, or on a local machine. For example, nvcr.io is the location of the NGC container registry for nvidia-docker images.

All nvcr.ioDocker images use explicit version-tags to avoid ambiguous versioning which can result from using the latest tag. For example, a locally tagged “latest” version of an image may actually override a different “latest” version in the registry.

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

This section is appropriate if you are using via a cloud provider.
Before pulling an nvidia-docker container, ensure that the following prerequisites are met:

To browse the available containers in the NGC container registry use a web browser to log in to your NGC container registry account on the website, https://ngc.nvidia.com.

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

Pulling A Container Using The NGC container registry Web Interface

This section is appropriate if you are using via a cloud provider.
Before you can pull a container from the NGC container registry, you must have Docker and nvidia-docker installed as explained in Preparing To Use NVIDIA Containers Getting Started Guide. You must also have access and logged into the NGC container registry as explained in NGC Getting Started Guide.
This task assumes:
  1. You have a cloud instance system and it is connected to the Internet.
  2. Your instance has Docker and nvidia-docker installed.
  3. You have access to a browser to the NGC container registry at https://ngc.nvidia.com and your account is activated.
  4. You want to pull a container onto your cloud instance.
  1. Log into the NGC container registry at https://ngc.nvidia.com.
  2. Click Registry in the left navigation. Browse the NGC container registry page to determine which Docker repositories and tags are available to you.
  3. Click one of the repositories to view information about that container image as well as the available tags that you will use when running the container.
  4. In the Pull column, click the icon to copy the Docker pull command.
  5. Open a command prompt and paste the Docker pull command. The pulling of the container image begins. Ensure the pull completes successfully.
  6. After you have the Docker container file on your local system, load the container into your local Docker registry.
  7. Verify that the image is loaded into your local Docker registry.
    $ docker images

    For more information pertaining to your specific container, refer to the /workspace/README.md file inside the container.