Development Environments#


A screenshot of the Desktop App open to the Project Container page for a project, showing affordances.

Overview of Project Environments#

Workbench provides development environments with containers. Each project has it’s own container, called the project container.

Projects can optionally have multi-container environments in addition to the project container, but this requires additional configuration by an end user.

Note

This page deals primarily with the single-container project environment. You can read about multi-container environments in the Compose Applications section.

Isolation / Customization#

  • Each project has it’s own container, called the project container, built from a base image

  • You can install packages with pip, conda, and apt

  • All dependencies get installed in the project container, including CUDA and JupyterLab

  • The contents of one container do not affect the other containers, nor the host machine

  • Containerization eliminates dependencies on the host machine beyond having Workbench installed

Reproducibility / Portability#

  • Dependencies are managed and versioned with configuration files

  • Workbench does some extra magic to handle bookeeping otherwise done manually by the user

  • Caveats:

    • (if GPU-accelerated) The host GPU drivers must match the CUDA version in the container

    • The workload/application should be configurable to match the host vRAM, RAM and CPU

    • Local/personal runtime options like API keys and sources for mounts must be configured

    • Dependencies should be pinned to ensure consistent container builds

The User Experience Is Simple#

  • You don’t need to know anything about containers or write a containerfile to use AI Workbench

  • You can select base images from a pre-configured list or use your own

  • You can modify the environment on the fly in the Desktop App or by editing files

  • Web apps running in the container are proxied so you can access them in the browser

Note

The best way to understand how Workbench environments work is work through the exercises in the Onboarding Project.

Configure, Build, Customize, and Run#

Configure#

Workbench uses metadata files and conventions to automate the handling of containers. The metadata files are stored in the project directory and versioned with Git.

Environment metadata files in the repository

File Name

Description

Location in project

Mandatory/Optional

Editable?

Spec file

Has the base image, package managers and runtime configuration like mounts

project/.project/spec.yaml

Mandatory

Do not edit

Requirements file

Specifies python packages to be installed on build

project/requirements.txt

Optional

Editable

Apt file

Specifies apt packages to be installed on build

project/apt.txt

Optional

Editable

Pre-build script

Customizes the build context

project/preBuild.bash

Optional

Editable

Post-build script

Customizes the container after packages are installed

project/postBuild.bash

Optional

Editable

Variables file

Has environment variables to be set at runtime

project/variables.yaml

Optional

Editable

Warning

Editing the spec.yaml file without following the specification or yaml formatting rules may cause an error when you try and view the project in the Desktop App.

If this happens, you can fix this by correcting the file so that Workbench can parse it.

Build#

Workbench uses the environment configuration files, information in the spec.yaml file, and information about the host machine to:

  • Render a containerfile that

    • Sets the build context with a default or as scripted by the preBuild.bash script

    • Uses the base image from the spec.yaml file

    • Includes the packages from the requirements.txt and apt.txt files

    • Includes the environment variables from the variables.yaml file

    • Runs any scripting from the postBuild.bash file

    • Specifies any sources on the host machine to be mounted in the container

  • Build the container with the containerfile

  • Store build information in a centralized folder, $HOME/.nvwb/project-runtime-info

Customize#

You can customize the environment either through the Desktop App or by editing the various configuration files in the project directory.

  • Install packages in the Desktop App or using the CLI

    • Will be installed into a running container

    • Will be built into the container on the next build

  • Install packages by editing the configuration files requirements.txt, apt.txt, preBuild.bash, or postBuild.bash

    • Will not be installed into a running container

    • Requires a rebuild of the container to take effect

These customizations are versioned by Git.

Run#

Environment variables

  • Workbench handles environment variables for the container as key-value pairs.

  • Unless you set environment variables in the pre-build or post-build scripts, Workbench will include environment variables as a runtime configuration by including the variables.yaml file.

  • Both the key and value are versioned.

Sensitive environment variables

  • Workbench handles secrets (like API keys as key-value pairs where the key is known and versioned but the value (i.e. the secret) is not in the repository or versioned

  • The value is confined to the host on which the secret is set. Workbench sets the value of the secret in the container at runtime

Mounts

  • Mounts are handled at runtime, and they are versioned in the spec file

  • You can set mounts in the Desktop App and CLI

GPU reservation

  • You can reserve a GPU for your project in the Desktop App and CLI

  • The reservation is specified in the spec file

  • The reservation will be handled at runtime. If insufficient GPUs are available, the container will not start and Workbench will alert you.

FAQs#

Do I need to know how to use containers to use Workbench?#

No. Absolutely zero container knowledge required. However, it will help you understand how things work.

Can I get root access in a running project container?#

No. The assigned user is workbench, and they do not have root access. Anything you need to do with sudo should be setup during the build through the post-build script.

Can I get root access while building the container?#

Yes. During build the user has passwordless sudo access, so you can install packages with apt and pip as the root user.

Why don’t you just use python virtual environments?#

They don’t fully address the needs of AI development environments.