About the SOE

A Standard Operating Environment (SOE) is a standardized set of tools, packages, and extensions designed to provide a consistent technical environment for computing tasks across an organization and it various platforms. This document outlines the components of the STEM SOE and provides guidance for setting up the SOE across different operating systems.

In industry, an SOE may also be referred to as a Golden Image or Golden Baseline.

STEM leadership's policy is to standardize on current Ubuntu LTS − 1: the Ubuntu LTS release immediately preceding the latest LTS, together with that release's default CPython minor version. The SOE manifest records the concrete release selections.

This target applies to Codio Boxes and Codio Virtual Desktop/standalone VMs, GitHub Codespaces, local Docker, and native Ubuntu installations. Windows and macOS use the same CPython minor series on their native operating systems. Existing Codio environments are to be migrated and qualified against this target. Course instructions, packages, and grading runtimes, including zyBooks where used, must be verified during that migration.

Security and patch updates within the manifest-selected Ubuntu release and Python minor series are permitted. Moving to a different Ubuntu LTS or Python minor version requires a reviewed and qualified SOE release; the selection does not advance automatically when a new LTS appears. Select the manifest-required CPython interpreter or install it alongside other versions rather than replacing the operating system's Python.

Table of Contents

1. Install the SOE
2. System Package Manager
3. System-Specific Packages
4. Scripting Languages
5. Source Control Management
6. Documentation Format
7. Extensible Code Editor

Install the SOE

On Your Computer

To install and configure the Standard Operating Environment (SOE) on your computer, select your operating system and follow the corresponding instructions.

• Windows
• macOS
• Linux

Dev Container

The SOE can also be set up within a development container (Dev Container) to provide a consistent and isolated development environment. Dev Containers use containerization technology to encapsulate the SOE and its dependencies, ensuring that the development environment is reproducible across different machines.

The default Dev Container for the SCR is GitHub Codespaces, which allows you to develop within a containerized environment directly from your browser or local development setup. Other containerization platforms, such as Docker, can also be used to create and manage Dev Containers for the SOE.

System Package Manager

A system package manager installs, updates, and removes software packages and manages their dependencies. The SOE uses command-line package managers to simplify software installation and maintenance across operating systems.

Windows

WinGet is Microsoft's command-line package manager for Windows. It installs, updates, and removes software from configured package sources. WinGet is distributed through Windows App Installer and is available on supported versions of Windows 10 and Windows 11.

macOS

Homebrew is a third-party package manager for macOS. It installs and manages command-line tools, applications, and supporting libraries that may not be included with the operating system. Homebrew must be installed separately on macOS.

Linux

Advanced Package Tool (APT) is the package management system used by Debian-based Linux distributions, including Ubuntu. It installs, updates, and removes software from configured package repositories while managing package dependencies. The SOE uses apt for interactive package management and apt-get for automated installation scripts.

System-Specific Packages

System-specific packages provide additional tools and dependencies needed to support the SOE on different operating systems. These packages may not be installed by default, and some are required only for particular development tasks.

Windows-Specific Packages

• Python Install Manager (PIM): Installs and manages Python runtime versions on Windows. It supports selecting and maintaining Python installations without manually managing separate installers.

• Git for Windows: Provides Git and Git Bash for Windows. Git Bash supplies a Bash-compatible shell environment and common Unix-style command-line utilities, supporting shell scripts and Git workflows on Windows.

• Windows Terminal (optional): Provides a terminal application with multiple tabs, panes, and configurable profiles for PowerShell, Command Prompt, Git Bash, and other command-line environments.

macOS-Specific Packages

• Command Line Tools for Xcode: Provides development utilities, compilers, and system libraries needed to build software and install packages that require compilation. It includes tools such as Git and Clang without requiring the full Xcode application.

• GNU Bash (Homebrew) (conditional): Provides a newer version of Bash than the version included with macOS. It supports modern Bash scripting features that may not be available in the operating system's bundled Bash interpreter.

Linux-Specific Packages

The following packages apply to Debian-based distributions, including Ubuntu.

• Python Virtual Environment Support (python3-venv): Enables Python to create isolated virtual environments for installing and managing project-specific packages without modifying the system-managed Python environment.

• Data Transfer and Archive Utilities (curl, unzip): Provide command-line tools for downloading files from remote servers and extracting ZIP archives. These utilities support automated software installation and resource management.

• Certificate Authorities (ca-certificates): Provides trusted certificate authorities used to verify secure TLS connections, supporting reliable downloads and communication with HTTPS services.

• Development Build Tools (build-essential) (optional): Provides essential compilation tools, including GCC, G++, and Make. These tools support building software from source code and installing dependencies that require native compilation.

Scripting Languages

Scripting languages allow users to execute commands, automate repetitive tasks, manage files and software, and process data. The SOE includes three cross-platform scripting languages: GNU Bash, PowerShell, and Python. Each provides different capabilities for system management, task automation, and working with data.

GNU Bash

GNU Bash is a command-line shell and scripting language commonly used for system administration and automation on Unix-like operating systems. It is particularly useful for executing operating-system commands, connecting command-line tools through pipelines, and automating tasks with shell scripts. Bash is widely available on Linux and macOS and is available on Windows through Git for Windows and the Windows Subsystem for Linux (WSL).

PowerShell

PowerShell is a cross-platform command-line shell, scripting language, and configuration management framework developed by Microsoft. Unlike traditional text-based shells, PowerShell uses an object-based pipeline, allowing commands to exchange structured data. It is particularly useful for managing operating-system resources, configuring software, and automating administrative tasks. PowerShell 7+ runs on Windows, macOS, and Linux.

Python

Python is a general-purpose programming language used in the SOE primarily for task automation. Its readable syntax and extensive library ecosystem make it particularly useful for processing structured data, manipulating files, interacting with application programming interfaces (APIs), and developing automation tools that require more complex program logic. Python runs on Windows, macOS, and Linux.

The approved runtime is the CPython minor series supplied by current Ubuntu LTS − 1, selected in the SOE manifest, on every platform. Select that interpreter in VS Code and create course virtual environments with it. Windows installations include the Python Install Manager (PIM), which manages Python versions; select the manifest-required runtime explicitly instead of an unqualified latest version.

Source Control Management

Source control management (SCM) tools track changes to files over time, maintain a history of revisions, and support collaboration on software projects.

Git is a distributed version control system that tracks changes to files and maintains a history of revisions. It allows users to create branches, compare versions, restore earlier revisions, and merge changes from different contributors. Git operates locally without requiring an internet connection and supports synchronization with remote repositories hosted on services such as GitHub. Git is available for Windows, macOS, and Linux.

GitHub is a cloud-based platform for hosting Git repositories and collaborating on software projects. It provides tools for managing repositories, reviewing proposed changes through pull requests, tracking tasks and defects through issues, and automating workflows with GitHub Actions. GitHub is accessible through a web browser and command-line tools, including the GitHub CLI, which enables users to manage GitHub resources directly from a terminal.

Documentation Format

Documentation formats define how information is structured, formatted, and presented. The SOE uses GitHub Flavored Markdown (GFM) to create readable, portable, and version-controlled documentation. Markdown format use plain-text files that can be edited in a code editor and rendered as formatted documents.

Markdown is a lightweight markup language used to create formatted documents using simple, readable plain-text syntax. It supports common document elements such as headings, paragraphs, lists, links, images, and code blocks without requiring specialized editing software. Markdown files are plain text and typically use the .md extension. They can be viewed and edited on Windows, macOS, Linux, and Web.

GitHub Flavored Markdown (GFM) is a standardized dialect of Markdown based on CommonMark, with additional syntax for tables, task lists, strikethrough text, and automatic URL linking. GFM is particularly useful for creating repository documentation, README files, project instructions, and task checklists that render directly on GitHub. It maintains Markdown's plain-text readability while providing additional formatting features for technical documentation and collaboration.

Extensible Code Editor

An extensible code editor provides tools for creating, viewing, and modifying source code and other text-based files. Extensions allow users to customize the editor with support for different programming languages, file formats, and development tools.

Visual Studio Code

Visual Studio Code (VS Code) is a free, cross-platform code editor developed by Microsoft. It provides syntax highlighting, code completion, an integrated terminal, debugging capabilities, and built-in Git integration. Its extensive extension ecosystem supports additional programming languages, linters, formatters, diagrams, and documentation tools. VS Code is available for Windows, macOS, Linux, and the web.

VS Code Extensions

Language Support

• PowerShell: ms-vscode.powershell
• Python:
  • Python Extension: ms-python.python
  • Pylance: ms-python.vscode-pylance

Code and Documentation Quality

• Python Linter and Formatter (Ruff): charliermarsh.ruff
• Code Spell Checker: streetsidesoftware.code-spell-checker
• Markdown Linter: DavidAnson.vscode-markdownlint

Diagramming and Visualization

• Visual Diagram Editor (Draw.io): hediet.vscode-drawio

Markdown Authoring and Export

• GitHub Markdown Preview: bierner.github-markdown-preview
• Markdown All in One: yzhang.markdown-all-in-one
• Markdown to PDF: yzane.markdown-pdf