Skip to content

SOE Adv

Michael Benson edited this page Nov 14, 2026 · 1 revision

GC-STEM SOE: Basic and Advanced Virtualization Profiles

Status: Proposed — Approved Concept; Implementation Deferred Date: 2026-11-14 Scope: GC-STEM SOE, CSO, and Course Reference Environment (CRE) architecture

1. Purpose

Define a maintainable approach for supporting basic development environments and optional advanced virtualization tools across GC-STEM course repositories.

The primary objectives are to:

  1. Provide functionally equivalent development environments for coursework.
  2. Establish one authoritative Course Reference Environment (CRE) per course.
  3. Minimize student setup requirements and technical support needs.
  4. Support faculty and STEM administrators who develop, test, and maintain course environments.
  5. Avoid duplicating SOE configurations, dependencies, and maintenance.
  6. Support Windows, macOS, and Linux where technically feasible.

Decision: Maintain one canonical STEM Standard Operating Environment (SOE) with an optional advanced virtualization profile. Do not create two independent SOEs.

2. Architecture

The GC-STEM environment consists of four related components:

Component Purpose
Basic SOE Common development tools and configurations
Advanced Virtualization Profile Optional host virtualization tools and supporting utilities
Course-Specific Overlay (CSO) Additional software and configurations required by a course
Course Reference Environment (CRE) Authoritative, tested environment for completing and evaluating coursework

Basic SOE

The Basic SOE is the default development environment for students.

It includes shared development tools such as:

  • Git and GitHub CLI
  • Python and common programming utilities
  • VS Code and standard extensions
  • Shared configurations and automation scripts
  • Environment verification tools

The current SOE remains the baseline. Advanced virtualization tools are not required for ordinary student installations.

Advanced Virtualization Profile

The Advanced Virtualization Profile extends the Basic SOE with optional tools for creating, running, and testing containers and virtual machines.

Its primary users are:

  • Faculty developing or maintaining courses
  • STEM deans and technical administrators
  • Advanced students whose coursework requires virtualization

The profile is optional and must not introduce unnecessary dependencies into the Basic SOE.

Course-Specific Overlay

Each course may define additional software, dependencies, and configurations in its CSO.

Courses requiring virtualization for instructional purposes may specify these tools as CSO requirements rather than relying on the optional advanced profile.

Course Reference Environment

Each course designates an authoritative CRE for completing, testing, and evaluating coursework.

Students may use alternative development environments when they are functionally equivalent for coursework.

When environment differences affect results, the designated CRE governs evaluation.

The CRE may be:

  • A local environment configured with the SOE and CSO
  • A validated container or virtual machine
  • A managed environment such as Codio

The CRE does not need to use identical host hardware or operating systems across all students.

Courses requiring specialized hardware, CPU architecture, GPU acceleration, or other computing capabilities may designate an appropriately configured managed environment as their CRE.

3. Proposed Tool Distribution

Tool or Capability Basic SOE Advanced Profile
Git / GitHub CLI Yes Inherited
Python and shared utilities Yes Inherited
VS Code and common extensions Yes Inherited
SOE/CSO verification Yes Inherited
Docker Engine / Docker Desktop No Optional
Docker CLI and Compose No With Docker
VirtualBox No Optional
Vagrant No Optional
WSL2 No Windows option
WSLc No Windows option
Hyper-V No Windows option
Multipass No Optional
Windows Sandbox No Windows testing option

Important: A virtualization tool may be installed separately when required by a course, even if the student does not use the Advanced Virtualization Profile.

The table describes the intended default installation profiles, not restrictions on which tools a course may require.

4. Host and Guest Responsibilities

Virtualization software generally requires installation or configuration on the host computer.

Examples include:

  • Docker Engine or Docker Desktop
  • VirtualBox
  • WSL2
  • Hyper-V
  • Multipass

These tools should not be installed indiscriminately inside ordinary SOE containers.

The architecture must distinguish between:

Host virtualization tools

Software responsible for creating and managing containers, virtual machines, or operating-system virtualization features.

Development and management utilities

Tools such as Docker CLI, image builders, container inspection utilities, and automation scripts that may operate within a supported container, virtual machine, or host environment.

Some management utilities can communicate with an external container runtime without running the virtualization engine themselves.

Host support, administrative permissions, processor architecture, and virtualization capabilities must be considered when selecting installation methods.

5. Platform Strategy

Primary Platforms

Docker

  • Primary container platform.
  • Supports consistent SOE and CSO container images.
  • Integrates with VS Code Dev Containers and GitHub Codespaces.
  • Supports publishing OCI images through GitHub Container Registry (GHCR).

VirtualBox

  • Preferred general-purpose full virtual machine platform where supported.
  • Suitable for testing complete guest operating systems.
  • Support depends on host architecture and guest operating system.

Windows Options

WSL2

  • Provides persistent Linux development environments on Windows.
  • May support native development and Linux container workflows.

WSLc

  • Optional Windows container runtime.
  • Evaluate compatibility with existing GC-STEM container workflows.
  • Do not assume Docker Compose compatibility without validation.

Hyper-V

  • Optional Windows virtualization platform.
  • Appropriate where supported by the Windows edition and host hardware.

Windows Sandbox

  • Disposable Windows testing environment.
  • Suitable for clean-environment installation and validation.
  • Not intended as a persistent student development environment.

Additional Platform

Multipass

  • Provides Ubuntu virtual machines across supported host platforms.
  • Useful for provisioning and testing Ubuntu environments.

Vagrant

  • Optional tool for reproducible VM provisioning.
  • May use supported local virtualization providers.
  • The current crs000 Vagrantfile remains an unimplemented placeholder.

No virtualization platform should be considered qualified for a course until its required workflow has been tested.

6. Published Images

The intended distribution model uses validated, versioned images rather than requiring every student to build an environment independently.

Container Images

Publish approved SOE and course-specific OCI images through GHCR.

Proposed image names:

  • ghcr.io/gc-stem/soe:<version>
  • ghcr.io/gc-stem/crs000:<version>
  • ghcr.io/gc-stem/<course-id>:<version>

These are proposed naming conventions, not confirmation that the images have been published.

Maintain Dockerfiles as the authoritative image build instructions.

Course images should reuse the shared SOE image where practical.

Virtual Machine Images

For courses requiring complete virtual machines, evaluate publishing validated VM images or reproducible provisioning configurations.

GitHub Releases may be suitable for smaller VM artifacts, subject to GitHub's file-size restrictions.

Larger VM images may require another distribution method.

Image Versioning

  • Publish versioned releases.
  • Pin container images by digest when exact reproducibility is required.
  • Validate images before publication.
  • Do not silently replace a course's approved reference image during a term.
  • Rebuild and revalidate images when incorporating security updates.
  • Retain sufficient build instructions and configuration to reproduce released environments.

Published images should remain traceable to their source code, configuration, and validation results.

7. Student Deployment Strategy

Normal Student Workflow

Students should use the simplest supported environment for their course.

Preferred options:

  1. Local development environment: Install and configure the SOE and any required CSO tools.
  2. Codio: Use the managed environment when provided or designated by the course.

Most students, especially in introductory courses, should not need to install advanced virtualization tools.

Temporary or Emergency Backup

GitHub Codespaces may provide temporary access to a course development environment when:

  • Working from another computer
  • Traveling
  • Experiencing local computer problems
  • Temporarily unable to access the normal development environment

Codespaces remains subject to account eligibility, usage limits, and billing policies.

Advanced Student Options

Students who need or prefer advanced deployment methods may use supported containers or virtual machines.

These options must remain functionally equivalent to the designated CRE for coursework.

8. Faculty and STEM Administrator Workflow

The Advanced Virtualization Profile primarily supports:

  • Developing and validating the SOE and CSOs
  • Testing clean installations
  • Building and verifying container images
  • Testing full virtual machines
  • Reproducing reported student environment problems
  • Evaluating compatibility across supported platforms
  • Validating course reference environments
  • Preparing and testing environment updates

Technical documentation useful to advanced students may remain in student-facing repositories.

Faculty-only procedures, internal administrative instructions, credentials, and restricted information belong in the corresponding crs000-faculty repository.

9. Configuration and Maintenance

Maintain one canonical source of SOE requirements.

Proposed responsibilities:

Location Responsibility
GC-STEM/SOE Shared tools, manifests, provisioning scripts, and verification
SOE/.config/soe_manifest.json Canonical SOE requirements
crs000/.config/cso_manifest.json Course-specific requirements
crs000/.devcontainer/ Course container and development environment configuration
crs000-faculty Faculty-only documentation and procedures
GHCR Published, validated container images

The Advanced Virtualization Profile should extend the existing SOE configuration rather than duplicate it.

The specific manifest structure, profile names, setup commands, and installation scripts will be determined during implementation.

Maintenance Principles

  1. Maintain one canonical SOE.
  2. Keep advanced virtualization optional.
  3. Use CSOs only for course-specific requirements.
  4. Avoid duplicating common dependencies and provisioning scripts.
  5. Reuse existing verification and automation tools.
  6. Make setup scripts safe to rerun where practical.
  7. Validate supported environments before publishing or recommending them.
  8. Keep primary student instructions separate from advanced deployment guidance.

10. Alternatives Evaluated

Architecture Advantages Disadvantages Decision
Two independent SOEs Clear separation Duplicate maintenance and configuration Reject
One SOE with optional advanced profile Common baseline, minimal duplication, flexible deployment Requires profile-aware provisioning Preferred
One SOE with all virtualization tools Single installation option Unnecessary software, complexity, and compatibility concerns Reject
One SOE with entirely separate virtualization tooling Clean separation More scattered setup and configuration Viable alternative

The preferred architecture balances simplicity, maintainability, and deployment flexibility.

11. Deferred Implementation Decisions

The following decisions are intentionally deferred:

  • Exact name and structure of the Advanced Virtualization Profile
  • Whether the profile uses the SOE manifest or a separate supplemental manifest
  • Which virtualization tools support automated installation on each host OS
  • Which tools require administrator privileges or additional host configuration
  • Whether the advanced profile includes management utilities within container images
  • Which container and VM image formats should be published
  • Whether all supported container architectures require published images
  • How to handle architecture-specific and GPU-dependent course requirements
  • How to integrate advanced-profile verification into soe.py
  • Which virtualization workflows require GitHub Actions validation
  • Which VM provisioning workflows should be supported through Vagrant or Multipass
  • Whether the advanced profile should be available through a separate installation command

These decisions should be based on demonstrated course and faculty needs rather than implementing every available virtualization technology.

12. Implementation Status

No implementation changes are authorized by this proposal.

The existing SOE, CSO, Dockerfile, Dev Container, WSL2, Windows Sandbox, and other provisioning configurations remain unchanged.

This document records an architectural direction for future evaluation and implementation.

13. Final Recommendation

Adopt one canonical GC-STEM SOE with an optional Advanced Virtualization Profile.

The Basic SOE remains the default for students. The advanced profile adds host virtualization capabilities for faculty, STEM administrators, and courses that require them.

Each course retains its CSO and designates one authoritative CRE.

The primary success criterion is functionally equivalent development environments for coursework, verified against the designated CRE.

The goal is not identical host hardware, operating systems, or virtualization platforms. It is consistent, reproducible execution and evaluation of course assignments.

Guiding principle: Standardize the required environment and expected behavior while minimizing student setup complexity and ongoing maintenance.