1. DGX Container Registry Overview

This guide is for first time users of the NVIDIA® DGX™ Container Registry. It explains the different user roles, how to set up new users on the DGX Container Registry, and how to push and pull container images to and from the DGX Container Registry.

1.1. General Workflow for Using DGX Container Registry

Using DGX Container Registry involves two areas – the NVIDIA DGX Cloud Services website and the Docker command line – as described in the following general flow:

  1. Activate your NVIDIA DGX Cloud Services account.
  2. Log on to the DGX Cloud Services website.
    • Obtain your API Key so you can access the DGX Container Registry.
    • Organization administrators can also create users and view available registry spaces and repositories.
    • Other users can view available registry spaces and repositories.
  3. From the Docker command line, access the DGX Container Registry and issue Docker commands such as pushing, pulling, or running Docker containers, depending on your user role.

1.2. Assumptions

This guide assumes the user is familiar with Linux and Docker, and has access to at least one DGX-1 system with Docker and nvidia-docker installed and configured for internet access.

2. DGX Container Registry Spaces and User Roles

2.1. DGX Container Registry Spaces

The following are the registry spaces available to DGX Container Registry users:

  • NVIDIA Public Registry

    Path: nvcr.io/nvidia/

    This space contains images provided by NVIDIA. All assigned users within a customer organization can pull images from this space.

  • Customer Organization

    Path: nvcr.io/org/

    This space is created for a customer organization during the initial DGX Container Registry setup.

    The organization administrator can push Docker images to this space for use by all users within their organization.

  • Customer Project

    Path: nvcr.io/org_project/

    This space is created by the organization administrator for use by other users within their organization who have been added to the project.

2.2. User Roles

DGX Container Registry supports three different user roles:

  • Organization Administrator

    Capabilities:

    • Create projects
    • Create users and assign them to one or more projects as Read-write or Read-only users
    • Push, pull, and run Docker images to and from all customer registry spaces
    • Pull and run Docker images from the NVIDIA public registry.
  • Read-write User

    The Read-write user role is applied on a per-organization or per-project basis. All users are automatically set up as Read-only users for the organization space, unless they have been specifically set up as a Read-write user for that space.

    Capabilities:

    • Pull, push, and run Docker images to and from any organization or project spaces of which the user is a member
    • Pull and run Docker images from the NVIDIA public registry
  • Read-only User

    The Read-write user role is applied on a per-organization or per-project basis. All users are automatically set up as Read-only users for the organization space, unless they have been specifically set up as a Read-write user for that space.

    Capabilities:

    • Pull and run Docker images from the NVIDIA public registry, from the organization space, and from any projects of which the user is a member

3. Setting Up DGX Container Registry

Before the customer organization attempts to use DGX Container Registry, the person responsible for ordering NVIDIA DGX Cloud Services should make sure that the following information has been provided to NVIDIA sales:

  • Organization name

    This name identifies the organization registry space that is available to all users in your organization.

  • Project name (optional)

    This name identifies an additional registry space that select users within your organization can use to share Docker images among a team within your organization.

  • Organization administrator name and email

    This is the person responsible for adding users and projects to the registry.

  • Authentication method for user accounts (IT-managed by SAML, or DGX account)

    IT-managed by SAML method integrates with your domain login as a single sign-on.

    DGX accounts are independent of your organization’s IT structure.

Once NVIDIA has received this information, the NVIDIA DGX team will set up the organization's space within DGX Container Registry, set up the administrator account and authentication method, and then send a welcome email to the administrator to inform that DGX Container Registry is available for use.

4. Administrator Instructions

4.1. Activating your NVIDIA DGX Cloud Services Account

In addition to providing access to software and container updates, your NVIDIA DGX Cloud Services account lets you access the optimized deep learning container images that are provided through the DGX Container Registry.

Before activating your NVIDIA DGX Cloud Services account, ensure that you have received an invitation email from the NVIDIA DGX team. The email confirms that the NVIDIA DGX team has set up your NVIDIA DGX Cloud Services account and that it is ready for you to activate.
  1. Follow the link in the e-mail to open the NVIDIA DGX Cloud Services account activation page in a browser.
  2. Follow the instructions on the NVIDIA DGX Cloud Services account activation page to activate your account. Depending on the authentication method set up by your organization, you may need to create a password or you may need to log in using your organization's single sign-on credentials.

4.2. Using the NVIDIA DGX Cloud Services Website

Log on to the DGX Cloud Services website.

The NVIDIA DGX Cloud Services website opens to a screen similar to the following:



Screen capture showing the organization administrator's initial view of the NVIDIA DGX Cloud Services website.

In the upper right corner is an icon representing you, the user, and the current registry space view.

4.2.1. DGX Container Registry Spaces – Initial View

The Container Registry area shows the registry spaces in the current view, as well as any Docker images that are stored there. All users can see the NVIDIA registry space containing DIGITS, CUDA and the Deep Learning Frameworks containers. This area is for read-only access to NVIDIA published containers.

The organization registry space and any other project spaces that have been set up will not appear until at least one Docker image is pushed to the space.

4.2.2. DGX Container Registry Spaces with Docker Repositories

The following example shows the organization space (acme) for a fictional Acme Corporation, and a project space (acme_zoom) for the Acme Zoom project after Docker images have been pushed to those spaces.



Screen capture showing organization and project registry spaces on the NVIDIA DGX Cloud Services website.

Note: A project space appears only if that project is in the current view. To switch registry space views, click your user icon at the upper right of the window, then select the organization or project space from the dropdown list.

This example shows the following registry spaces:

  • nvidia (nvcr.io/nvidia/)

    This is the NVIDIA registry space that is available for read-only access to all DGX users.

  • acme (nvcr.io/acme/)

    This is the organization registry space for the fictional company Acme Corporation. The organization administrator can push container images to this space to be shared with all users within the Acme organization. This area is private to this organization and cannot be seen by any other customers.

  • acme_zoom (nvcr.io/acme_zoom/)

    This is a project registry space (Acme Zoom) created by the organization administrator. Read-write users created under this project can push container images to this space to be shared with other members of the project. Read-only users under this project can pull and run containers from this space.

4.3. Creating Projects

Creating other projects is useful for allowing users to share images within a team while keeping them invisible to other teams in the same organization.

  1. Log on to the DGX Cloud Services website.
  2. Click Projects from the left navigation menu.
  3. Click Create Project.
  4. In the Create Project dialog, enter the project name and descriptions, and select whether or not the new project is a registry-only project. Members of registry-only projects cannot run Docker containers through the DGX Cloud Services website.
  5. Click Submit.

4.4. Creating Users and Changing User Roles

As the organization administrator, you must create user accounts in order to allow others to use the DGX Container Registry. Users are added to the organization space by default, and other projects can be created and then users added to those projects as needed.

4.4.1. Creating Users and Adding Them to Projects

  1. Log on to the DGX Cloud Services website.
  2. Select which registry space to add the user.

    If one or more projects are set up, click your user icon at the upper right corner and then select the organization space or one of the project spaces from the dropdown list.

    Note: If you select a project space, the user will automatically be added to the organization space as a Read-only user.
  3. Click Users from the left side menu, then click Add New User.
  4. Fill out the Add New User form for the new user as follows:
    1. Enter the display name and email where indicated.
    2. Click the Role Type list arrow and then select one of the user types.
  5. Click Submit when done.
An invitation email is automatically sent to the user.
Users can be members of more than one project. To add a user to another project, repeat these steps for any additional projects.

4.4.2. Changing User Roles

You can change user roles for any users you created. For example, if you added a user to a project when first creating the user, that user is automatically added to the organization space as a Read-only user. To allow that user to push Docker images to the organization registry space, you need to change that user’s role to Read-write for that space.
  1. Log on to the DGX Cloud Services website.
  2. Select which registry space for which you want to change the user role. Click your user icon at the upper right corner and then select the organization space or one of the project spaces from the dropdown list.
  3. Click Users from the left side menu. A list of all the users in the current registry space appears.
  4. Locate the user whose role you want to change, then click the pencil edit icon at the right side. The Edit User form appears.
  5. Click the Role Type list arrow and then select the new user type.
  6. Click Submit when done.

4.5. Using the DGX Container Registry

See User Instructions for instructions on how to use DGX Container Registry.

5. User Instructions

Before using DGX Container Registry from the Docker command line, you need to log on to the DGX Cloud Services website and obtain your API Key. Your API Key authenticates you to use the registry.

The DGX Cloud Services website also provides useful information, such as:

  • The DGX Container Registry spaces that are available to you
  • The Docker repositories in each space
  • Guidance on Docker push and pull commands

5.1. Activating Your DGX Cloud Services Account

After your organization administrator adds you as a user to the DGX Registry space, you will receive an invitation email.
  1. Click the link in the email to launch the DGX Cloud Services website account activation page in a browser.
  2. Follow the instructions to activate your account. Depending on the authentication method set up by your organization, you may need to create a password or you may need to log in using your organization's single sign-on credentials.

5.2. Using the NVIDIA DGX Cloud Services Website

Log on to the DGX Cloud Services website.



Screen capture showing the user's initial view of the NVIDIA DGX Cloud Services website.

When you log on to the website, the left section shows the DGX Container Registry spaces that you can access. These are indicated by the name adjacent to the network symbol.

  • nvidia (nvcr.io/nvidia/)

    This is the NVIDIA registry space that is available for read-only access to all DGX users.

  • acme (nvcr.io/acme/)

    This is the organization registry space for the fictional company Acme Corporation, and is available to all users within the Acme organization.

  • acme_zoom (nvcr.io/acme_zoom/)

    This is a project registry space (Acme Zoom) created by the organization administrator. Read-write users created under this project can push container images to this space to be shared with other members of the project. Read-only users under this project can pull and run containers from this space

5.2.1. Viewing the Repositories

The DGX Cloud Services website provides information about the repositories stored in each registry space.
  1. Click the name of the DGX Container Registry space to show or hide a list of Docker repositories that are stored in each space.
  2. Click one of the repositories to show a list of available tags for that Docker image as well as a readme that provides general information about the repository.
  3. To view the suggested pull command for a specific image and tag, hover over the tag and then click the download icon.

    Screen capture showing a sample docker pull command on the NVIDIA DGX Cloud Services website.

    You can copy this command to the clip board by clicking the copy icon to the right of the command.
  4. To view a model push command for the current registry space, click Push Command.

    Screen capture showing a sample docker push command on the DGX Cloud Services website.

    You will need to replace <repository:tag> with the corresponding information of the image that you want to push to the registry.

5.2.2. Switching Registry Space Views

A project space appears only if that project is in the current view.

  1. Click your user icon at the upper right of the window.
  2. Select the organization or project space from the dropdown list.

    Screen capture showing the user information for a user of the NVIDIA DGX Cloud Services website.

    This example shows:
    • The name of the user (John Smith) and login email (jsmith@example.com )
    • That John Smith belongs to the following registry spaces:
      • Acme Corporation (acme) organization space, which means that John Smith can access Docker images in nvcr.io/acme/.
      • Acme Zoom (acme_zoom) project space, which means that John Smith can access Docker images in nvcr.io/acme_zoom/.

5.2.3. Getting Your NVIDIA DGX Cloud Services API Key

Your NVIDIA DGX Cloud Services API key authenticates your access to DGX Container Registry from the command line.

CAUTION:
You need to generate your NVIDIA DGX Cloud Services API key only once. Anyone with your API key can access all the services and resources to which you are entitled through your NVIDIA DGX Cloud Services account. Therefore, keep your API key secret and don't share it or store it where others can see or copy it.
  1. Use a web browser to log in to your NVIDIA DGX Cloud Services account on the DGX Cloud Services website.
  2. In the top right corner, click your user account icon and select API KEY.



  3. In the API Key page that opens, click GENERATE API KEY .



    Note: If you misplace your API key, you can get a new API key from the DGX Cloud Services website whenever you need it. When you get your API key, a new key is generated, which invalidates any keys you may have obtained previously.
  4. In response to the warning that your old API key will become invalid, click CONTINUE.

    Your NVIDIA DGX Cloud Services API key is displayed with examples of how to use it.





    Tip: You can copy your API key to the clipboard by clicking the Copy icon to the right of the API key.

5.3. Using DGX Container Registry from the Docker Command Line

5.3.1. Accessing DGX Container Registry

You can access the DGX Container Registry by running a Docker command from your client computer. You are not limited to using your NVIDIA DGX platform to access the DGX Container Registry. You can use any Linux computer with Internet access on which Docker is installed.
Before accessing DGX Container Registry, ensure that the following prerequisites are met:
  • Your NVIDIA DGX Cloud Services account is activated.
  • You have an NVIDIA DGX Cloud Services API key for authenticating your access to DGX Container Registry. For more information, see Getting Your NVIDIA DGX Cloud Services API Key.
  • You are logged in to your client computer as an administrator user.

    An alternate approach for enabling other users to run containers without giving them sudo privilege, and without having to type sudo before each docker command, is to add each user to the docker group, with the command:

    sudo usermod -aG docker $USER

    While this approach is more convenient and commonly used, it is less secure because any user who can send commands to the docker engine can escalate privilege and run root level operations. If you choose to use this method, only add users to the docker group who you would trust with root privileges.

  1. Log in to the DGX Container Registry.
    sudo docker login nvcr.io
  2. When prompted for your user name, enter the following text:
    $oauthtoken

    The $oauthtoken user name is a special user name that indicates that you will authenticate with an API key and not a user name and password.

  3. When prompted for your password, enter your NVIDIA DGX Cloud Services API key as shown in the following example.
    Username: $oauthtoken
    Password: k7cqFTUvKKdiwGsPnWnyQFYGnlAlsCIRmlP67Qxa
    Tip: When you get your API key as explained in Getting Your NVIDIA DGX Cloud Services 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.

5.3.2. Loading an NVIDIA Docker Container onto your System

No NVIDIA Docker containers are preloaded onto your system. Instead, containers are available for download from the DGX Container Registry. NVIDIA has provided a number of containers for download from the DGX Container Registry. If your organization has provided you with access to any custom containers, you can download them as well.

Before loading an NVIDIA Docker container, ensure that the following prerequisites are met:
  • You have read access to the registry space that contains the container.
  • You are logged in to DGX Container Registry as explained in Accessing DGX Container Registry.
Tip: To browse the available containers in the DGX Container Registry, use a web browser to log in to your NVIDIA DGX Cloud Services account on the DGX Cloud Services website.
  1. Run the command to download the container that you want from the registry.
    sudo docker pull registry/registry-space/repository:tag
    registry
    The name of the container registry, which for the DGX Container Registry is nvcr.io.
    registry-space
    The name of the space within the registry that contains the container. For containers provided by NVIDIA, the registry space is nvidia.
    repository
    Repositories are collections of containers of the same name, but distinguished from each other by their tags. Think of it as the main container name.
    tag
    A tag that identifies the version of the container.
  2. To confirm that the container was downloaded, list the Docker images on your system.
    sudo docker images

The following example shows the commands for loading the December 2016 release (16.12) of the NVIDIA Caffe container and for confirming that the container was successfully loaded. This example shows the full command output.

~$ sudo docker pull nvcr.io/nvidia/caffe:16.12
16.12: Pulling from nvidia/caffe
04cf3f0e25b6: Pulling fs layer 
d5b45e963ba0: Pulling fs layer 
a5c78fda4e14: Pull complete 
193d4969ca79: Pull complete 
d709551f9630: Pull complete 
c4f10d5816c2: Pull complete 
03d19b47e3f6: Pull complete 
231461434bd3: Pull complete 
24dc76e8a57a: Pull complete 
11286505a13e: Pull complete 
c0b7802df453: Pull complete 
2c7190d40165: Pull complete 
b4e14a2856c8: Pull complete 
bb07303d2aa9: Pull complete 
7b44e6f6b31b: Pull complete 
1bd98944b62b: Pull complete 
760e4f26da15: Pull complete 
564efdae2d06: Pull complete 
9d7ad3031795: Pull complete 
a83bb85f8782: Pull complete 
8ff58fe01b92: Pull complete 
8c5870e63480: Pull complete 
f78f7c4c38be: Pull complete 
648f9f6f88f5: Pull complete 
600fdfb030b9: Pull complete 
Digest: sha256:a9441422dc506cb76136132a530bdae63b1753019ceb44f29e39eb0ff8f27528
Status: Downloaded newer image for nvcr.io/nvidia/caffe:16.12
~$ sudo docker images
REPOSITORY             TAG                 IMAGE ID            CREATED             SIZE
nvcr.io/nvidia/caffe   16.12               f2c0772c2e2d        3 weeks ago         3.436 GB

The following examples show commands for loading the NVIDIA DIGITS and Torch containers. The command output is omitted from these examples.

  • NVIDIA DIGITS December 2016 release (16.12):

    ~$ sudo docker pull nvcr.io/nvidia/digits:16.12
  • Torch December 2016 release (16.12):

    ~$ sudo docker pull nvcr.io/nvidia/torch:16.12

The following examples show commands for loading containers that are available to users who have read access to the acme organization space and acme_zoom project space. The command output is omitted from these examples.

  • Version 0.1 of the preloadedimage container in the acme organization space:

    ~$ sudo docker pull nvcr.io/acme/preloadedimage:0.1 
  • Version v1.5 of the mycaffe container in the acme_zoom project space:

    ~$ sudo docker pull nvcr.io/acme_zoom/mycaffe:v1.5

5.3.3. Tagging and Pushing a Container Image

Tagging and pushing a container image requires read-write access to the registry space that contains the container.

In the following examples, the user is a member of the Acme organization and the Zoom project within the Acme organization and has read-write access to the acme_zoom project space.

  • This example tags version v1.5 of the mycaffe local container image in the acme_zoom project space:

    ~$ sudo docker tag mycaffe nvcr.io/acme_zoom/mycaffe:v1.5
  • This example pushes version v1.5 of the mycaffe local container image to the acme_zoom project space:

    ~$ sudo docker push nvcr.io/acme_zoom/mycaffe:v1.5

6. Getting Support for DGX Container Registry

For additional information on using the DGX Container Registry and for getting help if you encounter issues, send an email to enterprisesupport@nvidia.com with a description of your issue and a ticket will be created for you.

Notices

Notice

THE INFORMATION IN THIS GUIDE AND ALL OTHER INFORMATION CONTAINED IN NVIDIA DOCUMENTATION REFERENCED IN THIS GUIDE IS PROVIDED “AS IS.” NVIDIA MAKES NO WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO THE INFORMATION FOR THE PRODUCT, AND EXPRESSLY DISCLAIMS ALL IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE. Notwithstanding any damages that customer might incur for any reason whatsoever, NVIDIA’s aggregate and cumulative liability towards customer for the product described in this guide shall be limited in accordance with the NVIDIA terms and conditions of sale for the product.

THE NVIDIA PRODUCT DESCRIBED IN THIS GUIDE IS NOT FAULT TOLERANT AND IS NOT DESIGNED, MANUFACTURED OR INTENDED FOR USE IN CONNECTION WITH THE DESIGN, CONSTRUCTION, MAINTENANCE, AND/OR OPERATION OF ANY SYSTEM WHERE THE USE OR A FAILURE OF SUCH SYSTEM COULD RESULT IN A SITUATION THAT THREATENS THE SAFETY OF HUMAN LIFE OR SEVERE PHYSICAL HARM OR PROPERTY DAMAGE (INCLUDING, FOR EXAMPLE, USE IN CONNECTION WITH ANY NUCLEAR, AVIONICS, LIFE SUPPORT OR OTHER LIFE CRITICAL APPLICATION). NVIDIA EXPRESSLY DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY OF FITNESS FOR SUCH HIGH RISK USES. NVIDIA SHALL NOT BE LIABLE TO CUSTOMER OR ANY THIRD PARTY, IN WHOLE OR IN PART, FOR ANY CLAIMS OR DAMAGES ARISING FROM SUCH HIGH RISK USES.

NVIDIA makes no representation or warranty that the product described in this guide will be suitable for any specified use without further testing or modification. Testing of all parameters of each product is not necessarily performed by NVIDIA. It is customer’s sole responsibility to ensure the product is suitable and fit for the application planned by customer and to do the necessary testing for the application in order to avoid a default of the application or the product. Weaknesses in customer’s product designs may affect the quality and reliability of the NVIDIA product and may result in additional or different conditions and/or requirements beyond those contained in this guide. NVIDIA does not accept any liability related to any default, damage, costs or problem which may be based on or attributable to: (i) the use of the NVIDIA product in any manner that is contrary to this guide, or (ii) customer product designs.

Other than the right for customer to use the information in this guide with the product, no other license, either expressed or implied, is hereby granted by NVIDIA under this guide. Reproduction of information in this guide is permissible only if reproduction is approved by NVIDIA in writing, is reproduced without alteration, and is accompanied by all associated conditions, limitations, and notices.

Trademarks

NVIDIA, the NVIDIA logo, and DGX-1 are trademarks and/or registered trademarks of NVIDIA Corporation in the Unites States and other countries. Other company and product names may be trademarks of the respective companies with which they are associated.