Before starting the process of bringing your own container, ensure you understand the requirements for your container of interest. Once you are ready to proceed, navigate to the .project/spec.yaml file of your project and scroll to the environment section, which will be the focus of this page.
In this reference, let’s discuss how to bring your own custom container to a project. Bringing your own container primarily requires editing the environment section of the project spec file and rebuilding the environment. Here is one example of a project’s spec file.
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: '[ \$(echo url=\$(jupyter lab list | head -n 2 | tail
-n 1 | 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: ...
“Core Modifications” are defined as changes that must occur to swap out the project container. Without these changes properly implemented, your project may not be built properly.
“Recommended Modifications” are defined as best-practice changes that should occur when swapping out the project container. These are primarily fields that are used by the backend of the NVIDIA AI Workbench client software. Your project may still build and components may still function; however, your experience with working on the project inside the AI Workbench UI may be impacted.
“Optional Modifications” are defined as fields of the project spec that do not need to change. You may find filling in certain fields relevant to your project on a case-by-case basis, but in general, these fields do not need to be touched and/or are auto-filled by AI Workbench upon rebuild.
Core Modifications
Container Registry (registry)
Description: The container registry containing the base image. AI Workbench will use this as part of the container build process.
Action: Provide the container registry for your container of interest; if you have the Dockerfile, you may need to first build the container and push it to a registry.
Example Usage:
registry: nvcr.io
Container Image (image)
Description: The container image on top of which the Project container will be built.
Action: Provide the container image (and tag, if any) for your container of interest; if you have the Dockerfile, you may need to first build the container and push it to a registry. Also include the namespace if needed, but do not include the registry.
Example Usage:
image: nvidia/pytorch:23.12-py3
Name (name)
Description: Name of the base container. Considered non-optional because AI Workbench will show the old container information in the UI if left unchanged.
Action: Provide a name for the container.
Example Usage:
name: PyTorch
Description (description)
Description: Description of the base container. Considered non-optional because AI Workbench will show the old container information in the UI if left unchanged.
Action: Provide a brief and informative description of the container.
Example Usage:
description: A Pytorch 2.1 Base with CUDA 12.2
CUDA Version (cuda_version)
Description: Version of CUDA installed in the base environment. Considered non-optional because AI Workbench will match with drivers incorrectly if not updated.
Action: Specify the version of CUDA installed in this container, or leave blank if not applicable.
Example Usage:
cuda_version: "12.2"
Recommended Modifications
Package Managers (package_managers)
Description: Section containing a list of objects with information about the installed package managers. This information is used by AI Workbench on the backend to track project package installation in the base container image. Note that if this remains unchanged, the package manager widget will likely not work, especially if you are working with a venv or conda environment.
Action: For each package manager in the container, specify the name of the package manager, the complete path to the manager binary, and a comma-separated list of packages installed by that manager.
Example Usage:
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: []
Package Manager Environments (package_manager_environment)
Description: Section describing the package manager environment that should be activated before installing packages and starting applications. This field can be useful when working with virtual environments inside the container.
Action: Specify the type of environment that should be activated as well as the target path or name of the environment to activate. If not applicable, leave the fields blank.
Example Usage:
package_manager_environment: name: conda target: /opt/conda
User Info (user_info)
Description: Section describing information about what user the container processes should run as. AI Workbench automatically provisions a user for you as you run the container, but this is an option to override. For example, depending on the base container you may need to run the project as a root user.
Action:
uid- The configured UID of the user within the container. Set to"0"to force the container to run as root.gid- The configured GID of the user within the container. Set to"0"to force the container to run as root.username- The username of the user within the container. Set to"root"to force the container to run as root.
Example Usage:
user_info: uid: "0" gid: "0" username: "root"
Applications (apps)
Description: Section containing a list of objects describing the applications already installed in the base environment.
Action: Specify the following sub-fields for each application. Note
webapp_optionsshould be defined ifclassis awebapp.name- Name of the application, displayed to the user.type- The type of application, used to determine what application-specific automation will be run.class- The class of application, used to determine what optional configuration options are available, eg. webapp, process, or native.start_command- The shell command used to start the application. Must not be a blocking command.health_check_command- The shell command used to check the health or status of the application. A return of zero means the application is running and healthy. A return of non-zero means that the application is not running or unhealthy.stop_command- The shell command used to stop the application.user_msg- An optional string template with a message that will be displayed to the user when the application is running.icon_url- An optional link to the icon or image used for displaying the application.webapp_options- Ifclassis specified as awebapp, the following option(s) are available.autolaunch- A boolean indicating if the AI Workbench should automatically open the application URL for the user.port- The port that the application will be running on.proxy- The following option(s) are available.trim_prefix- A boolean indicating if the AI Workbench reverse proxy should remove the application-specific Url prefix before forwarding the request to the application.
url- The static URI used to access the application. ORurl_command- The shell command used to get the URI for the application. The output from this command is considered the URL.
Example Usage:
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: '[ \$(echo url=\$(jupyter lab list | head -n 2 | tail -n 1 | 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' - ...
Supported Architectures (supported_architectures)
Description: List of supported architectures that the base environment image is built to be compatible with for metadata purposes.
Action: Provide a list of supported architectures for your container, or leave as a blank list if not applicable.
Example Usage:
supported_architectures: - "amd64" - "arm64"
Programming Languages (programming_languages)
Description: List of programming languages installed in the base environment for metadata purposes.
Action: List the programming languages installed in this container, or leave blank if not applicable.
Example Usage:
programming_languages: - python3
Labels (labels)
Description: List of labels for the base environment. Consider these as search term keywords or descriptors for your container.
Action: Specify a list of search term keywords or labels to be attached alongside your container.
Example Usage:
labels: - cuda12.2 - pytorch2.1
Image Version (image_version)
Description: Version number of the container image used by AI Workbench for metadata purposes.
Action: Provide the version number of the container image, if any.
Example Usage:
image_version: 1.0.3
OS (os)
Description: Name of the base environment operating system used by AI Workbench for metadata purposes.
Action: Provide the name of the base environment operating system.
Example Usage:
os: linux
OS Distribution (os_distro)
Description: Name of the base environment operating system distribution used by AI Workbench for metadata purposes.
Action: Provide the name of the base environment operating system distribution.
Example Usage:
os_distro: ubuntu
OS Distribution Release (os_distro_release)
Description: Release version of the base environment operating system distribution used by AI Workbench for metadata purposes.
Action: Provide the release version of the base environment operating system distribution.
Example Usage:
os_distro_release: "22.04"
Optional Modifications
Build Timestamp (build_timestamp)
Description: Timestamp of image build in Y/m/d/H/M/S format. No manual updates are necessary as this field gets updated automatically by AI Workbench on container build.
Schema Version (schema_version)
Description: Metadata for the version of the base environment container label schema currently read by AI Workbench. Currently on
schema_version: v2, so there is no need to update this field. However, if incorrect the project will break.
Entrypoint Script (entrypoint_script)
Description: Path to script that will be sourced when the Project container starts as an option for further project environment customization.
Action: If your project requires any action at the beginning of the project container start, we provide a location for an entrypoint script you may want to use. Provide the location to the script here.
Example Usage:
entrypoint_script: /path/to/script.sh
Icon URL (icon_url)
Description: Link to the icon or image used for the base environment. Otherwise, AI Workbench will apply defaults. This feature is coming soon.
Action: If you would like AI Workbench to display an icon as part of this base environment, link the URL to the icon image here or leave it blank for defaults.
Example Usage:
icon_url: https://my-website.com/my-image.png
Once finished editing the specifications for your project, you should rebuild the project environment for your changes to take effect.
On CLI:
Save your changes.
Open the project in the Active context, if not already open.
nvwb buildto rebuild the project environment.
On Desktop:
Save your changes.
Open the project in the Active context, if not already open.
On the bottom left corner of the window, select the Build tab. Select Build to rebuild the project environment. Alternatively, select Rebuild within the Environment Tab of the project.