Development Environments#

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 |
|
Mandatory |
Do not edit |
Requirements file |
Specifies python packages to be installed on build |
|
Optional |
Editable |
Apt file |
Specifies apt packages to be installed on build |
|
Optional |
Editable |
Pre-build script |
Customizes the build context |
|
Optional |
Editable |
Post-build script |
Customizes the container after packages are installed |
|
Optional |
Editable |
Variables file |
Has environment variables to be set at runtime |
|
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
scriptUses the base image from the
spec.yaml
fileIncludes the packages from the
requirements.txt
andapt.txt
filesIncludes the environment variables from the
variables.yaml
fileRuns any scripting from the
postBuild.bash
fileSpecifies 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
, orpostBuild.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.