Use Your Own Base Container

When you create a new Workbench Project, you typically choose one of the NVIDIA-provided base container environments available from the NVIDIA NGC Catalog.

If you want to use one of the pre-built containers and make simple customizations, such as adding a package, see Customize Your Environment Quickstart.

Use this documentation in the following cases:

• You want to create a fully-custom container for reuse — If you want to create a fully-custom container that you can use for you own projects, or that you can publish and share with other AI Worbench users, see the section Create a fully-custom container for AI Workbench. This is an advanced scenario.

• You want to customize the base container for a single project — If you want to change the behavior of the base container for a single project, see the section Customize a base container.

To create a fully-custom container to use as a base environment for AI Workbench projects, you build and expose the metadata for the image by creating Docker labels for your image.

An image can have multiple labels, however each key in a label must be unique. Labels in parent images are inherited but can be overridden in child images. For more information, see Docker object labels.

To allow for easy parsing of label keys and values, while avoiding inadvertent overriding of values, a strict label schema convention is defined. The convention is <domain-name>.<spec-field>, where domain-name is com.nvidia.workbench and spec-field is the base environment specification’s field name. For example:

• com.nvidia.workbench.programming_languages

It is your responsibility as the base image creator to gather the required information from the parent images, and cumulate and append the information from the parent images while defining these labels. The string defined in the com.nvidia.workbench.image-version label is used to sort multiple images from newest to oldest. These strings represent the semantic versions of the image, and are used to sort and order image versions in the UI/ CLI. If this label is not specified, the image tags are string-sorted to determine the display order.

Use the information in the following table to create the Docker labels for your custom container image. For a description of each field, see Modify your spec.yaml file.

If you want to change the behavior of the base container for a single project, you can manually edit the metadata contained in the spec.yaml file. For an example spec.yaml file, see Example spec file.

First you modify your spec.yaml file, and then you rebuild your project environment.

Modify your spec.yaml file

To use your own container, navigate to the .project/spec.yaml file of your project, and scroll to the environment section. For an example spec.yaml file, see Example spec file.

Use the following list to determine what changes you must make to your spec file.

• Change Required — Changes that must occur to customize the project container. Without these changes, your project does not build correctly.

• Change Recommended — Best-practice changes that you should make to the project container. These are fields that are used by the NVIDIA AI Workbench client software. Your project might still build, and components might still function; however, your experience working on the project inside the AI Workbench UI might be negatively impacted.

• Change Optional — Change these fields only if they are relevant to your project.

Use the information in the following table to edit your spec file.

            

            
supported_architectures:

  - "amd64"
  - "arm64"
        

            

            
labels:
    - cuda12.2
    - pytorch2.1
        

            

            
apps:
- name: jupyterlab
  type: jupyterlab
  ...
        

            

            
programming_languages:
    - python3
        

            

            
user_info:
    uid: "0"
    gid: "0"
    username: "root"
        

            

            
package_managers:
- name: conda
  binary_path: /opt/conda/bin/conda
  installed_packages:
  - python=3.9.18
  - pip
- name: apt
  binary_path: /usr/bin/apt
  installed_packages:
  - ca-certificates
  - curl
- name: pip
  binary_path: /opt/conda/bin/pip
  installed_packages: []
        

Specify apps in your container

If your custom base container has applications pre-installed, use the information in the following table to specify them in your spec file.

            

            
webapp_options:
  autolaunch: true
  port: "8888"
  proxy:
    trim_prefix: false
  url_command: <your command>
        

            

            
webapp_options:
  autolaunch: true
  port: "6006"
  proxy:
    trim_prefix: false
  url: http://localhost:6006
        

Rebuild your project environment

Whenever you directly change the spec.yaml file, you must perform a complete rebuild of the project container before you can access the changes.

Rebuild by using the desktop application

To rebuild your environment by using the AI Workbench desktop application, do the following.

1. In AI Workbench, on the Environment page, if your environment is running, click Stop Environment.

   Wait until you see Build Required next to Environment.

2. Click Start Build.

   The project builds. Wait until you see Build Ready in the status bar.

3. Click Start Environment.

Rebuild by using the CLI

To rebuild your environment by using the AI Workbench CLI, do the following.

1. Run the following command to stop your container environment. If the container is already stopped you see a message that the container is not running. Continue to the next step.

   Copy

   Copied!

               
   
               
   nvwb stop --container
           

2. Run the following command to rebuild your project.

   Copy

   Copied!

               
   
               
   nvwb build
           

   The project builds. Wait until you see Container build complete and then go to the next section to test your new package.

3. Run the following command to start your container environment.

   Copy

   Copied!

               
   
               
   nvwb start --container
           

Example spec file

The following is one example of a spec file for a Workbench Project.

            

            
  specVersion: ...
  meta: ...
  layout: ...
  environment:
    base:
      registry: nvcr.io
      image: vjrv0zpbsw9c/internal/pytorch:1.0.3
      build_timestamp: "20231212000523"
      name: PyTorch
      supported_architectures: []
      cuda_version: "12.2"
      description: A Pytorch 2.1 Base with CUDA 12.2
      entrypoint_script: ""
      labels:
      - cuda12.2
      - pytorch2.1
      apps:
      - name: jupyterlab
        type: jupyterlab
        class: webapp
        start_command: jupyter lab --allow-root --port 8888 --ip 0.0.0.0 --no-browser
          --NotebookApp.base_url=\$PROXY_PREFIX --NotebookApp.default_url=/lab --NotebookApp.allow_origin='*'
        health_check_command: '[\$(echourl=\$(jupyterlablist|head-n2|tail
          -n1|cut-f1-d''''|grep-v''Currently''|sed"s@/?@/lab?@g")|curl
          -o/dev/null-s-w''%{http_code}''--config-)==''200'']'
        stop_command: jupyter lab stop 8888
        user_msg: ""
        icon_url: ""
        webapp_options:
          autolaunch: true
          port: "8888"
          proxy:
            trim_prefix: false
          url_command: jupyter lab list | head -n 2 | tail -n 1 | cut -f1 -d' ' | grep
            -v 'Currently'
      - name: tensorboard
        type: tensorboard
        class: webapp
        start_command: tensorboard --logdir \$TENSORBOARD_LOGS_DIRECTORY --path_prefix=\$PROXY_PREFIX
          --bind_all
        health_check_command: '[\$(curl-o/dev/null-s-w''%{http_code}''http://localhost:\$TENSORBOARD_PORT\$PROXY_PREFIX/)
          ==''200'']'
        stop_command: ""
        user_msg: ""
        icon_url: ""
        webapp_options:
          autolaunch: true
          port: "6006"
          proxy:
            trim_prefix: false
          url: http://localhost:6006
      programming_languages:
      - python3
      icon_url: ""
      image_version: 1.0.3
      os: linux
      os_distro: ubuntu
      os_distro_release: "22.04"
      schema_version: v2
      user_info:
        uid: ""
        gid: ""
        username: ""
      package_managers:
      - name: apt
        binary_path: /usr/bin/apt
        installed_packages:
        - curl
        - git
        - git-lfs
        - vim
      - name: pip
        binary_path: /usr/local/bin/pip
        installed_packages:
        - jupyterlab==4.0.7
      package_manager_environment:
        name: ""
        target: ""
  execution: ...