For Teachers and Admins

Vocareum Notebook's container architecture enables customized lab environments to meet your curriculum's needs.

Introduction to Container Images

In Vocareum, lab environment refers to the development environment available to users when they launch a lab, including all packages and configurations. The Container Image applied to an assignment dictates the lab environment.

The default Vocareum Notebook Container Image runs Ubuntu Linux and has many common computer and data science packages pre-installed. Custom Container Images capture the differences between the default Vocareum Notebook container and your updated lab environment, ensuring a quick lab startup.

To create a custom Container Image, simply make your changes in the Configure Workspace view and then click "Save Image," which captures:

Any packages installed globally using the sudo command.
All files and configurations added outside of the /voc directory.

In contrast to the lab environment, lab content in Vocareum refers specifically to files in the /voc folder. The Container Image does not control lab content. Instead, the /voc folder auto-saves continuously in both Configure Workspace and student work areas. For more information on the /voc folder, refer to Navigating the Vocareum Files Browser.

Guides

Detailed guides for creating and applying custom Container Images.

Installing Packages Globally

Select a Vocareum Notebook assignment from the course page and navigate to "Configure Workspace" to access the assignment authoring environment.
Open the Terminal, located in the Apps menu of your Vocareum Notebook.
From the terminal, install your package globally using pip3 with the sudo command:
```
sudo pip3 install <package>
```

To release your changes to student environments, you will need to create a custom container image using a simple process described in the following section of this article: Creating and Saving A Custom Image.

Modifying the Environment

If you want to configure any aspects of the environment beyond installing packages with pip, you will need to make those changes outside of the /voc folder to ensure they persist in your custom Container Image.

Select a Vocareum Notebook assignment from the course page and navigate to "Configure Workspace" to access the assignment authoring environment.
Open the Terminal, located in the Apps menu of your Vocareum Notebook.
From the terminal, exit the /voc folder by navigating to the root directory:
```
cd /
```
Complete your configuration anywhere outside the /voc directory.
1. If you are installing a command line application that is not available in the pip ecosystem, we recommend installing it in the /opt folder and configuring the appropriate paths to ensure it is discoverable in the lab environment.

Creating and Saving a Custom Container Image

Once you have completed your changes to the lab environment, you can release these changes to learner environments by creating a custom container image.

In the Configure Workspace assignment authoring environment, select Save Image in the top right area of your notebook:
In the "Save Container Image" modal that opens:
1. Give the new image a name in the "Lab name" field.
2. Leave the "Replace current image" box checked if you would like to replace the container image for the current assignment with the new image you are creating.
3. Leave the "Restart running container" box checked if you would like to restart the container of your current assignment authoring workspace to begin using the new container image yourself.
When you are done with your selections in the "Save Container Image" modal, press the Save button.

The new lab environment will now be available for all learners next time they start their labs.

Applying a Custom Container Image to a Lab

Once a custom Container Image has been created, you can apply it to an assignment any time in the Assignment Part settings.

Select a Vocareum Notebook assignment from the course page and click the name of the assignment part you wish to edit to open the settings menu.
In the Lab Definition section of the assignment part settings, locate the Container Image dropdown and select the name of your custom image.
Click the Save Part button to save the assignment part settings.

Saving the part will immediately replace the Container Image with your new selection.

Releasing a New Lab Environment to Students

When you replace a lab Container Image, the new image is immediately released to all users. This is true regardless of whether you replace the image in the Save Container Image modal or in the Assignment Part settings.

Users do not need to Reset their labs to receive an updated Container Image; their lab environment will be up to date automatically the next time it launches.

However, if a user is actively running their lab when you replace the Container Image, their environment will not change until they restart their kernel or leave and re-enter the lab. Unlike a lab Reset, restarting the kernel is a non-destructive action that will not modify or remove any existing files in the user's work folder.

Installing Packages Locally

In some cases, you may wish to install packages locally in your working directory rather than modify the Container Image for all users.

For example, Teachers and Admins editing assignments in the "Configure Workspace" view may wish to install packages locally for testing purposes. Note that any packages installed locally while authoring an assignment will be available to you within your own work directory but will not be available in Student View, nor will they be saved in the environment when you use the "Save Image" feature.

Additionally, student users may want to install packages for their own use. Since students do not have sudo access to the lab environment, they can only install packages locally.

To install packages locally:

Open the Terminal, located in the Apps menu of your Vocareum Notebook.
Install packages locally using the pip command:
```
pip3 install <package>
```

Local pip packages are located in the /voc/work/.local/lib/python3.10 directory.