Is this page helpful?

AI Workbench Project Containers#


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

Overview#

AI Workbench provides your development environment through a container.

However, you don’t need to know anything about containers because AI Workbench handles things under the hood. If you already use containers, then the mechanics of AI Workbench should be intelligible.

You can interact with the container entirely through the Desktop App.

AI Workbench is an abstraction layer on top of the Git repo and the container. You can do everything through the Desktop App, VS Code and JupyterLab. Alternatively, you can use the CLI in a terminal.

You define the container through configuration files versioned in the project.

You can add Python packages through requirements.txt and Debian packages through an apt.txt file. More complex things are possible by scripting with the preBuild.bash and postBuild.bash files.

AI Workbench automatically manages the build and runtime configuration - It’s all declarative.

You don’t need to wrangle the containers for things to work. You just manually edit the configuration files or in the Desktop App. AI Workbench handles the details in a structured and reproducible way.

Key Concepts#

Project Spec File:

The .project/spec.yaml YAML file that defines the base image and containerfile.

Environment Configuration Files:

Five files in the project repository used to build and run the project container: preBuild.bash, apt.txt, requirements.txt, postBuild.bash and variables.env.

Base Image:

An existing container image for the starting point for the build. Defined in .project/spec.yaml.

Project Runtime Folder:

A separate folder that defines the currently implemented container.

Build Context:

Project runtime sub-folder that stages environment configuration files to copy into the build.

Runtime Configuration:

Settings (key-value pairs) that AI Workbench applies when starting the container. Stored in the variables.env file. Not available during the container build.

Container Management#

AI Workbench automates a three step process to build and run the project container.

  1. Cloning/creating a project automatically creates a containerfile from the .project/spec.yaml

  2. AI Workbench runs the containerfile to build the container image on the location

  3. Starting the container or an application configures and launches the runtime

AI Workbench separates the container build context from the project repository.

For various reasons, AI Workbench does NOT build the container in the project repository. Instead, it creates and populates a separate runtime folder by translating files from the project repository.

This is a little unconventional, especially in comparison to doing things manually.

Manual changes to configuration files are only implemented when you restart or rebuild the container.

AI Workbench monitors differences between the project files and counterparts in the project runtime folder but it won’t implement any changes without you restarting or rebuilding the container.

For example, editing the environment configuration will trigger a variety of notifications in the Desktop App but they will not show up in the container until you restart/rebuild it.

Build Context Limitations#

The AI Workbench created build context only has the containerfile, package files and build scripts.

This keeps things simple and clean, but it blocks including anything else in the project (environment variables, source code, data files).

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

Do NOT refer to files in the project repository in 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 repository

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