Quickstart in CLI

This guide is a basic tutorial for getting started with NVIDIA AI Workbench. It will walk you through activating the context on your local system, creating a project, and launching a Jupyterlab application. It will also give you an idea of how to modify the environment, manage the container, create versions, and publish local work to GitHub.

CLI Prerequisites

  • You successfully installed the application on your local system.

  • You have configured your NGC API key and your GitHub credentials. You can verify this with the nvwb list integrations command.

  • You have opened a new shell.

  • You have set the user.name and user.email in Git.

  • You are familiar with the user docs.

Step 1: Creating a Project and Opening JupyterLab

Here, you create a blank project using an available Default Base Image on NGC, open a Jupyter Notebook running in the container, print “Hello World!” and then make your first commit.

  1. Check the available Contexts on your system. Since we have yet to add any Remote Contexts, the only Context available is the local system.

    Copy
    Copied!
                

    nvwb list contexts

    The output will look like the following:

    Copy
    Copied!
                

    NAME │ DESCRIPTION │ HOSTNAME │ STATUS ────────┼────────────────────────────────┼───────────┼───────────────── local │ Default local context for │ localhost │ ⚫ Not Running │ working on 'mac' │ │


  2. Run the following command to start the local context:

    Copy
    Copied!
                

    nvwb activate local

    Your prompt will prepend (nvwb:local)

  3. Create a Project by running the command below, following directions, and hitting Return:

    Copy
    Copied!
                

    nvwb create project

    You will enter the name <project_name>, a description, and select from one of the two available bases, Python Basic or Pytorch Basic.

  4. Once the Project container is built, you can open the Project with the command:

    Copy
    Copied!
                

    nvwb open <project_name>

    The directory will change to ~/nvidia-workbench/<project_name> and ~/nvidia-workbench/<project_name> will prepend to the prompt.

  5. To open JupyterLab, run the following command and wait for a browser tab to open:

    Copy
    Copied!
                

    nvwb start jupyterlab [--no-gpus]

    Note

    The --no-gpus flag is only necessary if you used the Pytorch container and the local system does not have a GPU.


  6. When JupyterLab is open, navigate to the code directory in the browser, create a new notebook, print “Hello World!” and save the notebook.

  7. To see that you`ve changed the Project state, run the following command:

    Copy
    Copied!
                

    nvwb status

    Note

    The status is similar to a Git status, but it gives information about the state of the environment in addition to those files. In this case, you should see that you added a file.


Step 2: Modifying the Environment and Rebuilding the Container

Here, you will add some Python dependencies and rebuild the container to ensure they are available.

  1. To add Python packages, open the requirements.txt file and enter the packages you want. Then, save the file.

  2. To see that you`ve changed the Project state, run the status command:

    Copy
    Copied!
                

    nvwb status

    You will see that you also modified a file and that the environment requires a Full Rebuild. That is because you changed your requirements.txt file, but the container hasn`t been rebuilt.

  3. To rebuild the container, run the following command:

    Copy
    Copied!
                

    nvwb build

    Note

    This triggers a container rebuild to install the dependencies; however, the current container is still running.


  4. Once the container rebuild is completed, you can work in the new environment by stopping the running container and then starting JupyterLab again by:

    Copy
    Copied!
                

    nvwb stop jupyterlab nvwb start jupyterlab


You will see that you can import the packages added. Do that and then save the notebook.

Step 3: Adding Code and Data to the Project

The Project folder is available at ~/nvidia-workbench/<project_name>, and you can add code and data directly through your file browser into the code and data folders in that directory.

  1. Add some code and data that will work with the environment you have built through the selection of the Base Environment and Python dependencies you added.

    Note

    You can do this by dragging and dropping in the file browser or copying or moving into the code and data folders.


  2. In JupyterLab, adjust the paths for the code and data to work for the directory structure.

  3. Save the changes.

Step 4: Checking Status, Making a Commit and Publishing to GitHub

After Steps 1 through 3, you have created a simple local Project. Now it is time to check the status, commit your work, and push it to GitHub.

  1. Check the changes you`ve made to the Project by running the command:

    Copy
    Copied!
                

    nvwb status

    Note

    You should see that you’ve modified a file and added files but that the environment does not require a rebuild.


  2. Commit the changes by running the command below and hitting Return:

    Copy
    Copied!
                

    nvwb commit

    Note

    AI Workbench formulates the commit message for you.


  3. Now, publish the Project to GitHub so you can store it or move it to a different system by running the following command:

    Copy
    Copied!
                

    nvwb publish https://github.com <user_name> private

    Note

    <user_name> is the user name associated with the GitHub account you authenticated to, while private keeps the repository private.


  4. Now, go to https://github.com/<user_name>/<project_name> to see the project.

Congrats, you are now ready to get started with NVIDIA AI Workbench!

Previous Running Applications with CLI
Next Deep Dive: Breaking Down the Project Spec
© Copyright 2023-2024, NVIDIA. Last updated on Jan 21, 2024.