For Admins

Vocareum's Container Image Management feature allows organization administrators to create and manage custom container images for use in lab environments. With this feature, you can build new images from Vocareum's defaults, bring your own Docker images, and track versions — giving you full control over the software environments your students and instructors work in.

This guide walks you through the complete workflow for creating, building, validating, and managing container images.

Custom container image workflows

There are two ways to create or update an image, both of which populate a shared Container Image catalog for your organization:

From the Container Image Management page: build an image from a Vocareum base image, upload a Dockerfile, or import your own Docker image. You can also open any existing image in the Sandbox, change it interactively, and save the result as a new image, without creating an assignment. This workflow is available to organization Admins and is the focus of this article.
From Configure Workspace: while editing an assignment, make changes in the lab and select Save Image to capture them as a new image, directly in the flow of authoring. This workflow does not require the Container Image Management page or a Dockerfile, and it is available to Teachers and Admins. For details, refer to Installing Packages in Vocareum Labs.

The Container Image Management page centralizes management of all images, so that Admins have one place to create, review, version, and remove them. The Configure Workspace workflow remains available so that Teachers and Admins can create images as the need arises while building an assignment.

Who Should Read This

This article is intended for organization administrators (Admins) who need to configure and manage container images for their institution's Vocareum courses and labs.

Prerequisites

You must have Admin privileges in your Vocareum organization.
Familiarity with container concepts (Docker images, Dockerfiles) is highly recommended but not required.
If bringing your own image, you will need access to your Docker image source (Dockerfile, repository URL, or image files).

Accessing the Container Image Management Page

To access the Container Image Management interface, navigate to your organization's admin panel in Vocareum. The page displays all available container images, including default Vocareum images and any custom images created by your team.

Default Vocareum images view:

Custom Images view:

Creating a New Container Image

Follow these steps to create a new custom container image.

Define Image Details

Click the Add Image button on the Container Image Management page.
Enter a descriptive Image Name that clearly identifies the purpose of this image (for example, "Data Analysis Jupyter Notebook").
Add a Description explaining what software and tools are included in this image.
Assign an Image Tag for version tracking. This tag is immutable once set — choose a meaningful version identifier (for example, v1.0, data_analysis_jupyter_v1).

Provide the Build Source

You can provide the build source for your image in one of several ways:

From a default base image: Select one of Vocareum's pre-configured base images and customize it with additional packages or configurations.
From a Dockerfile: Upload a Dockerfile that defines your custom environment from scratch.

Configure the Build

Fill in the build configuration form. The available fields depend on the build source type you selected when providing the build source.

If customizing from a base image

Select a Base image from the dropdown. The page will display the corresponding FROM line you need to include in your Dockerfile.

Under Docker build files, upload your Dockerfile or a .zip archive containing the Dockerfile and any supporting files it references (for example, scripts, config files, datasets, or dependencies).

Example Dockerfile:

FROM 036136800740.dkr.ecr.us-west-2.amazonaws.com/jupyter-2004:1.67

# Install any additional dependencies if needed
# For example, to install pandas, numpy, matplotlib, seaborn, scikit-learn, and plotly:
RUN pip install \
    pandas \
    numpy \
    matplotlib \
    seaborn \
    scikit-learn \
    scipy \
    plotly \
    ipywidgets

When building from a base image the access ports are automatically filled with the necessary ports but, If your image needs to expose specific ports or application endpoints, click + Add access entry and provide the Protocol, Port, and Path for each entry.

If building from scratch

Enter the User ID (UID) — the numeric user ID that processes in the container will run as (for example, 1001).
Enter the Group ID (GID) — the numeric group ID associated with the container user (for example, 100).
Enter the Persistent workspace directory — the path inside the container where the user's work area will be mounted (for example, /voc/work).

Example Dockerfile:

FROM jupyter/scipy-notebook:python-3.11

# Install any additional dependencies if needed
# For example, to install pandas, numpy, matplotlib, seaborn, scikit-learn, and plotly:
RUN pip install \
    pandas \
    numpy \
    matplotlib \
    seaborn \
    scikit-learn \
    scipy \
    plotly \
    ipywidgets

CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--ServerApp.token=''", "--ServerApp.password=''", "--ServerApp.tornado_settings={\"headers\":{\"Content-Security-Policy\":\"frame-ancestors *\"}}"]

Important: If building from scratch, ensure the container can be iframed. The lab will be embedded in the platform via an iframe.

For example Jupyter must be started with the following flag to allow the container to be iframed:

--ServerApp.tornado_settings={"headers":{"Content-Security-Policy":"frame-ancestors *"}}

If your image needs to expose specific ports or application endpoints, click + Add access entry and provide the Access entry name, Protocol, Port, and Path for each entry (for example, name: Jupyter, protocol: HTTP, port: 8888, path: /lab).

Build the Image

Once the form is complete, click the Build image button to start the image build process.
Monitor the build progress in the interface.
If the build fails, review the error messages, click Cancel, modify your build source, and click Build image again.

Testing and Iterating in the Sandbox

The Sandbox is a simplified version of Configure Workspace that lets you open an existing image, confirm it works, and optionally turn it into a new image, all without creating an assignment.

Always validate your image in the Sandbox before using it in a live assignment. This ensures students will have a working environment from day one.

To open the Sandbox, do either of the following on the Custom Images tab:

Select Open Sandbox on the image's row.
Select View Details on the image's row, then select Open Sandbox in the image details window.

In the Sandbox, you can:

Validate an image: confirm that the required software, packages, and configuration are present and working, exactly as a learner would experience them.
Create a new image from an existing one: make changes to the environment, then select Save Image to save those changes as a new image. The new image appears on the Custom Images tab alongside the original. This is the same Save Image action available in Configure Workspace, so you can iterate on an image without opening an assignment.

Saving Custom Images from Lab Environments

Teachers and Admins can also create custom images directly from a lab environment using the Save Image feature:

While working in a lab environment, configure the container with the desired software and settings.
Click Save Image to capture the current state of the container as a new image.
Enter an image tag for version tracking when prompted.
The saved image will appear on the admin-facing Container Image Management page, where Admins can review and manage it.

This is useful for instructors who want to customize a lab environment for specific assignments without needing to write a Dockerfile.

For the full procedure, including what the image captures and how to release it to learners, refer to Installing Packages in Vocareum Labs.

Version Tracking and Image Tags

Every container image in Vocareum is assigned an immutable tag for version tracking. This ensures that you always know exactly which version of an image is being used in each lab profile.

Tags cannot be changed once assigned — to update an image, create a new version with a new tag.
Use a consistent naming convention for tags across your organization (for example, v1.0, v1.1, or date-based like 2026-spring).

Tips and Best Practices

Start from defaults when possible: Vocareum's base images are pre-configured for common use cases. Extending them is faster and more reliable than building from scratch.
Test thoroughly in the sandbox: The sandbox mirrors the student experience. Use it to catch issues before they affect your class.
Use descriptive names and tags: Clear naming helps your team identify and manage images as your library grows.
Document your images: Keep notes on what each image contains and which courses use it, so your team can maintain them over time.

Managing Container Images in Vocareum