Is this page helpful?

AI Workbench Project Containers#

Overview#

AI Workbench builds a container for your development environment.

The container is defined from the project spec file and the (optional) configuration files. See here.

The spec file defines the base image and other build information, while the configuration files provide package lists and scripts to be run during the build.

AI Workbench formats the information into containerfile that it runs to build the container.

AI Workbench runs the container using the configuration defined in the repository.

It formats the runtime command from information pulled from the spec file (e.g. GPUs to mount, secret names), the variables.env file, and the project runtime folder (secret values). The information (except for secret values) is versioned in the repository itself. See here.

Key Concepts#

Project Container

The container that AI Workbench builds and runs for your development environment.

Environment Configuration Files

Optional files in the repository used to build and run the project container. Divided into “package files” (apt.txt, requirements.txt), “build scripts” (preBuild.bash, postBuild.bash), and “variables” (variables.env and entries from spec.yaml).

Base Image

The starting container image used as a foundation for the project container. It is pulled from a container repository specified by a URL in the project spec file, .project/spec.yaml.

Project Runtime Folder

Folder AI Workbench creates on the host to cache environment information that lives outside of the project repository.

A sub folder of ~/.nvwb/project-runtime-info that contains copies of the environment configuration files, the formatted entrypoint and containerfile, as well as the user specific secrets that shouldn’t be kept in the repository.

Build Context

An isolated folder with generated files (entrypoint, containerfile) and copied files from the project.

Runtime Configuration

User entered settings applied when starting the container.

Includes the key-value pairs stored in the variables.env, the GPU configuration information in the spec.yaml file, and the secrets keys from the project runtime folder.

Container Management#

Configuration file edits are tracked, and diffs cue up a container rebuild/restart to implement changes.

For example, editing the environment configuration triggers Desktop App notifications but the actual changes aren’t implemented until you restart/rebuild the project container.

AI Workbench has a three step, managed process to build the container.

  1. It copies the project spec and environment files into the project-runtime-info folder on the host

  2. Then it formats an entrypoint script and a containerfile and puts them that runtime folder

  3. Then it builds the container from the containerfile

It does NOT put the formatted entrypoint or containerfile in the repository. This is a little unconventional, especially in comparison to doing things manually.

AI Workbench can run commands in the container to manage applications, packages and files.

You can start and stop applications and manage packages using features in the Desktop App and CLI. AI Workbench has the commands configured and runs them in the container.

For web applications, the proxy service provides a single configuration for ports, so you don’t need to stop/start the container to add ports.

Build Context Limitations#

The build context can’t access the entire project repository or the environment variables.

The build context is prescriptively limited to the following files:

  • The formatted entrypoint and containerfile

  • The optional configuration files from the repository (if present)

  • The spec file

Furthermore, you can’t manually add things to the build context because it is dynamically generated.

You must account for the fixed build context when writing the preBuild.bash or postBuild.bash scripts.

For example, the following will fail in the build scripts:

  • Invoking environment variables defined in variables.env

  • Direct pip or apt installs from source files in the project

  • Copying files from the project

  • Changing directory into /project/

However, you can add dependencies from external sources. PyPi installs should be done using the package files. pip installs from GitHub should be done in one of the build scripts.

Furthermore, there are workarounds to include custom, locally defined packages during the build or at runtime. You can find them in the How To sections.