Repository navigation
SOE Adv
Status: Proposed — Approved Concept; Implementation Deferred Date: 2026-11-14 Scope: GC-STEM SOE, CSO, and Course Reference Environment (CRE) architecture
Define a maintainable approach for supporting basic development environments and optional advanced virtualization tools across GC-STEM course repositories.
The primary objectives are to:
- Provide functionally equivalent development environments for coursework.
- Establish one authoritative Course Reference Environment (CRE) per course.
- Minimize student setup requirements and technical support needs.
- Support faculty and STEM administrators who develop, test, and maintain course environments.
- Avoid duplicating SOE configurations, dependencies, and maintenance.
- 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.
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 |
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.
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.
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.
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.
| 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.
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.
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.
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.
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
crs000Vagrantfile remains an unimplemented placeholder.
No virtualization platform should be considered qualified for a course until its required workflow has been tested.
The intended distribution model uses validated, versioned images rather than requiring every student to build an environment independently.
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.
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.
- 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.
Students should use the simplest supported environment for their course.
Preferred options:
- Local development environment: Install and configure the SOE and any required CSO tools.
- 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.
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.
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.
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.
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.
- Maintain one canonical SOE.
- Keep advanced virtualization optional.
- Use CSOs only for course-specific requirements.
- Avoid duplicating common dependencies and provisioning scripts.
- Reuse existing verification and automation tools.
- Make setup scripts safe to rerun where practical.
- Validate supported environments before publishing or recommending them.
- Keep primary student instructions separate from advanced deployment guidance.
| 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.
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.
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.
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.