Understanding the ODS Installer Directory Structure: A Complete Guide

The ODS installer directory structure organizes installation logic into three distinct layers: a core orchestrator at ods/install-core.sh, pure-function libraries in ods/installers/lib/, and sequential installation phases in ods/installers/phases/, with platform-specific wrappers for macOS and Windows.

The ODS installer directory structure in the Osmantic/ODS repository follows a modular design that separates concerns across multiple directories. This architecture enables the installer to run consistently across Linux, macOS, and Windows while maintaining clean abstractions between imperative installation steps and reusable utility functions.

Overview of the ODS Installer Directory Layout

The installer resides under the top-level ods/ directory. Inside this folder, the structure splits into logical components that handle orchestration, library functions, phase execution, and platform adaptation. This separation ensures that pure functions remain side-effect-free and testable, while installation phases handle the imperative work of setting up the system.

The Three Core Layers

Core Orchestrator (install-core.sh)

At ods/install-core.sh, the core orchestrator serves as the main entry point for Linux systems. This thin driver sources the pure-function libraries and then executes the thirteen sequential installation phases in order. It sets the INSTALL_PHASE environment variable and manages the flow from preflight checks through the final summary.

Pure-Function Libraries (lib/)

The ods/installers/lib/ directory contains only side-effect-free helper functions. These scripts handle tasks like tier-mapping, GPU detection, and logging without modifying the system state. Key files include tier-map.sh, which maps detected hardware to ODS tiers (CPU, AMD, NVIDIA, Apple), and detection.sh, which identifies CPU/GPU types and OS versions at runtime.

Installation Phases (phases/)

Located at ods/installers/phases/, this directory holds thirteen ordered Bash scripts numbered 01 through 13. Each phase implements a specific installation step and is sourced by the orchestrator in strict sequence. Notable phases include 01-preflight.sh for environment sanity checks, 02-detection.sh for hardware detection, 05-docker.sh for Docker-Compose setup, and 13-summary.sh for generating the final installation report.

Platform Abstraction Layer

Dispatch Helper (dispatch.sh)

The ods/installers/dispatch.sh script determines the host platform and forwards execution to the appropriate wrapper. This dispatch mechanism ensures users can invoke a single entry point regardless of operating system, with the script automatically selecting the correct implementation path.

macOS and Windows Wrappers

Platform-specific adaptations live in ods/installers/macos/ and ods/installers/windows/. These directories contain wrapper scripts such as install-macos.sh and install-windows.ps1 that adapt the generic installer to their respective operating systems. Both wrappers ultimately invoke the same core phases while handling OS-specific prerequisites like Homebrew or PowerShell execution policies.

Common Utilities

The ods/installers/common.sh file provides shared Bash snippets used across multiple phases. It contains error handling routines and progress display functions that ensure consistent user feedback throughout the installation process.

How to Run the ODS Installer

Execute the installer using different entry points depending on your operating system.

On Linux systems, run the core orchestrator directly:

bash ods/install-core.sh

On macOS, use the platform wrapper:

bash ods/installers/macos/install-macos.sh

On Windows, execute the PowerShell wrapper:

powershell -ExecutionPolicy Bypass -File ods/installers/windows/install-windows.ps1

Each method ultimately calls ods/installers/dispatch.sh to route execution through the appropriate platform layer before sourcing the phase scripts in sequential order.

Summary

• The ODS installer directory structure separates concerns into three layers: orchestration, libraries, and phases
• Core orchestrator at ods/install-core.sh drives the installation sequence across thirteen numbered phases
• Pure-function libraries in ods/installers/lib/ provide testable, side-effect-free utilities for hardware detection and tier mapping
• Installation phases in ods/installers/phases/ execute imperative setup steps from preflight (01) through summary (13)
• Platform wrappers in ods/installers/macos/ and ods/installers/windows/ enable cross-platform support with minimal code duplication
• Dispatch logic in ods/installers/dispatch.sh automatically routes execution to the correct platform-specific implementation

Frequently Asked Questions

Where is the main entry point for the ODS installer on Linux?

The main entry point for Linux systems is ods/install-core.sh. This orchestrator script sources the thirteen installation phases in sequential order and coordinates the entire setup process from the repository root.

How does the ODS installer handle different operating systems?

The installer uses a dispatch pattern where ods/installers/dispatch.sh detects the host platform and forwards execution to platform-specific wrappers. These wrappers in ods/installers/macos/ and ods/installers/windows/ adapt the generic installation logic to handle OS-specific requirements while reusing the same core phase scripts.

What is the purpose of the lib/ directory in the ODS installer?

The ods/installers/lib/ directory contains pure-function libraries like detection.sh and tier-map.sh that perform side-effect-free operations such as hardware detection and tier classification. This separation allows these utilities to be tested independently and reused across multiple installation phases without risking unintended system modifications.

How many installation phases does the ODS installer execute?

The ODS installer executes thirteen sequential phases located in ods/installers/phases/, numbered 01 through 13. These range from 01-preflight.sh for initial environment checks to 13-summary.sh for final reporting, with each phase handling a specific aspect of the setup process like Docker configuration or dependency installation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}