Is this page helpful?

AI Workbench Project Containers#

Overview#

AI Workbench builds a container image for your development environment.

The image 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 renders the information in a containerfile that it runs to build the container image.

AI Workbench creates and runs a project container using the configuration stored in the repository.

When you start a project, AI Workbench creates a container from the image and configures it with the runtime configuration from the project spec and other files in the repository.

This includes settings such as environment variables, mounts, networking, and GPU access. The runtime configuration (except for secret values) is versioned with the repository. See here.

Your code, data and configuration are stored in the repository outside of the container.

The repository is stored on disk and mounted into the container at runtime. This allows your files to persist and be portable independently of the container’s ephemeral file system.

The project container is removed each time you stop the project.

The container is a temporary runtime environment. Removing it ensures that the latest runtime configuration is applied the next time you start the project container. This lets you update the environment and prevents stale runtime state.

Key Concepts#

Base Image

The starting 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.

Container Build Scripts

Optional user-edited scripts in the repository (preBuild.bash, postBuild.bash) that AI Workbench includes during the container build. Use them to script modifications that become part of the container image.

Environment Configuration Files

Optional package files (apt.txt, requirements.txt) in the repository that AI Workbench includes during the container build to let you add packages.

Build Context

An isolated folder with AI Workbench-generated files (entrypoint, containerfile) and selected files copied from the project repository.

Generated Entrypoint

An entrypoint.sh file that AI Workbench dynamically renders into the build context. The generated entrypoint coordinates the preserved base-image entrypoint, the project startup script, and removal of passwordless sudo before the normal project container process begins. AI Workbench does not store this generated file in the project repository.

Project Container

The container that AI Workbench runs for your development environment. It uses the base image as a starting point and includes additional runtime configurations.

Runtime Configuration

User-entered settings applied when starting the container.

Includes the key-value pairs stored in the variables.env, the GPU configuration in the spec.yaml file, and the secrets keys from the project runtime folder. Also includes the startup script (onStart.bash).

Startup Script

Optional script (onStart.bash) that AI Workbench runs every time it creates and starts the project container. The script can access the mounted project and running container environment without the limitations of the build context. It runs with temporary passwordless sudo access during container startup.

Project Runtime Folder

A sub folder of ~/.nvwb/project-runtime-info that AI Workbench creates on the host to cache environment information that lives outside of the project repository.

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 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.

Container Management and Use#

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

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

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

  1. Copy the project spec and build-related files, including container build scripts and environment configuration files, into the project runtime folder on the host.

  2. Render an entrypoint script and containerfile in the project runtime folder.

  3. Build the container image from the containerfile.

AI Workbench does not put the generated entrypoint or containerfile in the repository.

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.

Project Container Startup#

AI Workbench runs project startup customization after it mounts the project.

The generated entrypoint runs the preserved base-image entrypoint first and then runs the project-root onStart.bash script. Unlike build scripts, onStart.bash can access files in the project mount.

The startup script initializes each newly created project container.

It runs as the project user with passwordless sudo available until the script finishes. Passwordless sudo is not available in the normally running project container after startup. For startup behavior and editing procedures, see Use the onStart.bash Script.