Skip to main content

How to Manage Container Images in Vocareum

Learn how organization admins can create, build, and manage custom container images in Vocareum — including creating images from defaults, importing Docker images, and tracking versions with tags.

S
Written by Shingo Nakagaki

Container Image Management

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.

Who Should Read This

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

Prerequisites

  • You must have org-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'll 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 image management 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:

Step 1: Define Image Details

  1. Click the Add Image button on the Container Image Management page.

  2. Enter a descriptive Image Name that clearly identifies the purpose of this image (e.g., "Data Analysis Jupyter Notebook").

  3. Add a Description explaining what software and tools are included in this image.

  4. Assign an Image Tag for version tracking. This tag is immutable once set — choose a meaningful version identifier (e.g., v1.0, data_analysis_jupyter_v1).

Step 2: 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.

Step 3: Configure the Build

Fill in the build configuration form. The available fields depend on the build source type you selected in Step 2:

If customizing from a base image:

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

  2. Under Docker build files, upload your Dockerfile or a .zip archive containing the Dockerfile and any supporting files it references (e.g., 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

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

  1. Enter the User ID (UID) — the numeric user ID that processes in the container will run as (e.g., 1001).

  2. Enter the Group ID (GID) — the numeric group ID associated with the container user (e.g., 100).

  3. Enter the Persistent workspace directory — the path inside the container where the user's work area will be mounted (e.g., /voc/work).

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

    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 *"}}

  5. 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 (e.g., name: Jupyter, protocol: HTTP, port: 8888, path: /lab).

Step 4: Build the Image

  1. Once the form is complete, click the Build image button to start the image build process.

  2. Monitor the build progress in the interface.

  3. If the build fails, review the error messages, click cancel, modify your build source, and click Build image again.

Step 5: Validate the Image

  1. Once the build completes, use the Open Sandbox (student view container) to validate that the image works as expected.

  2. Test that all required software, libraries, and configurations are present and functioning correctly in the sandbox environment.

  3. If the image needs adjustments, modify your build source and rebuild.

Important: Always validate your image in the sandbox before using it in a live lab profile. This ensures students will have a working environment from day one.

Saving Custom Images from Lab Environments (Instructors)

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

  1. While working in a lab environment, configure the container with the desired software and settings.

  2. Click Save Image to capture the current state of the container as a new image.

  3. Enter an image tag for version tracking when prompted.

  4. The saved image will appear on the admin-facing Container Image Management page, where org-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.

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 (e.g., 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.

Related Resources

Did this answer your question?