How ODS Installation Phases Are Executed: Sequential Orchestration in Osmantic/ODS

The ODS installer executes installation phases sequentially through ods/install-core.sh, which sets the INSTALL_PHASE environment variable and sources each phase script from ods/installers/phases/ in strict order, aborting on any non-zero exit code via a trap handler.

The Osmantic/ODS (Open Data Services) platform utilizes a deterministic, phase-driven installation architecture to ensure reliable deployment across diverse hardware environments. At its core, a hardened Bash orchestrator coordinates 13 distinct installation phases through direct script sourcing, enforcing strict error boundaries and comprehensive logging via shared library functions.

The Orchestration Engine in install-core.sh

The file ods/install-core.sh functions as the central orchestrator for the entire setup workflow. After loading pure-function libraries from ods/installers/lib/ (including constants.sh and logging.sh), the script initiates a linear execution pipeline that processes each phase exactly once.

According to the source implementation (lines 38-63), the installer updates the global INSTALL_PHASE environment variable to a human-readable identifier before sourcing the corresponding phase script. This pattern ensures that diagnostic tools and logging functions always know the current execution context, while maintaining clean separation between phases.

Sequential Phase Execution Mechanism

Each installation phase follows a strict sourcing protocol that guarantees deterministic execution order. The orchestrator explicitly assigns INSTALL_PHASE immediately before loading the phase logic using standard Bash source commands.

# In ods/install-core.sh (excerpt)

INSTALL_PHASE="01-preflight";    source "$SCRIPT_DIR/installers/phases/01-preflight.sh"
INSTALL_PHASE="02-detection";    source "$SCRIPT_DIR/installers/phases/02-detection.sh"
INSTALL_PHASE="02b-external-services"; source "$SCRIPT_DIR/installers/phases/02b-external-services.sh"
INSTALL_PHASE="03-features";     source "$SCRIPT_DIR/installers/phases/03-features.sh"
INSTALL_PHASE="04-requirements"; source "$SCRIPT_DIR/installers/phases/04-requirements.sh"
INSTALL_PHASE="05-docker";       source "$SCRIPT_DIR/installers/phases/05-docker.sh"

# …continues through phase 13

Because these operations use source rather than sub-shell execution, each phase inherits the set -euo pipefail environment established at the top of install-core.sh. This inheritance means any unhandled error or undefined variable within a phase immediately propagates to the orchestrator's error handling system.

The 13 Installation Phases

The ODS installer progresses through 13 sequential phases, each encapsulated in a dedicated script under ods/installers/phases/:

• 01-preflight: System validation and prerequisite verification
• 02-detection: Hardware detection (GPU, CPU architecture) and OS tier classification
• 02b-external-services: Configuration of external dependencies and service endpoints
• 03-features: Determination of optional services to enable based on detected capabilities
• 04-requirements: Installation of required system packages and command-line tools
• 05-docker: Docker engine installation and user permission configuration
• 06-12: Intermediate steps covering service deployment, network configuration, and health validation
• 13-summary: Final report generation and installation confirmation (designed to never fail)

Each phase script contains a standardized header documenting its inputs, outputs, and failure modes, ensuring long-term maintainability and operational transparency.

Error Handling and Abort Logic

The installer implements fail-fast semantics through a combination of strict shell options and signal traps. The cleanup_on_error trap, defined early in ods/install-core.sh, intercepts non-zero exit statuses and prints contextual diagnostic information—including the current $INSTALL_PHASE—before terminating the process.

This error handling applies uniformly across all phases because the source command executes phase logic within the main shell process. If 01-preflight.sh detects insufficient disk space and exits with code 1, the orchestrator immediately triggers cleanup without proceeding to 02-detection.sh, preventing partial system modifications.

When invoked with the --dry-run flag, the installer still sequences through all phases and updates INSTALL_PHASE, but underlying system commands are replaced with no-op or echo-only logic, enabling safe validation of the installation workflow.

Running and Customizing Installation Phases

Standard Installation Execution

Invoke the full phase sequence from the repository root:

cd ods
./install.sh               # Interactive installation

./install.sh --tier 2 --no-voice --non-interactive  # Automated deployment

Manual Phase Inspection

Developers can source individual phases directly for debugging or targeted execution:

#!/usr/bin/env bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/installers/lib/constants.sh"
source "$SCRIPT_DIR/installers/phases/04-requirements.sh"

Extending with Custom Phases

Add new installation steps by creating phase scripts and registering them in the orchestrator:

# 14-custom.sh – a new optional step

#!/usr/bin/env bash
ods_progress 5 "custom" "Running custom step"
show_phase 14 1 "Custom Phase" "~10 seconds"

# custom logic here …

Register the extension in ods/install-core.sh:

INSTALL_PHASE="14-custom"; source "$SCRIPT_DIR/installers/phases/14-custom.sh"

Summary

• ODS installation phases execute sequentially through ods/install-core.sh, which acts as the central orchestrator by loading libraries and sourcing phase scripts in order.
• Each phase runs via Bash source after the INSTALL_PHASE variable is updated, ensuring accurate progress tracking and error context.
• Error handling leverages set -euo pipefail and a cleanup_on_error trap that aborts immediately when any phase returns a non-zero exit code.
• All 13 phases reside in ods/installers/phases/ and follow consistent documentation patterns describing inputs, outputs, and execution time estimates.
• Dry-run mode allows safe preview of phase execution without modifying system state or installing packages.
• Developers can manually source phases for debugging or extend the installation sequence by appending new source commands to the orchestrator.

Frequently Asked Questions

What happens if one ODS installation phase fails?

If any phase returns a non-zero exit code, the cleanup_on_error trap defined in ods/install-core.sh immediately intercepts the failure, prints diagnostic information including the current INSTALL_PHASE value, and terminates the installer. Because phases are sourced rather than executed as sub-processes, errors propagate directly to the orchestrator's error handler, preventing inconsistent or partial system states.

Can I skip specific phases during ODS installation?

No, the current architecture does not support selective phase skipping. The orchestrator hard-codes the sequential sourcing of all 13 phases in ods/install-core.sh (lines 38-63). To bypass specific functionality, you must modify the relevant phase script directly or fork the repository and comment out the specific source line, though this may destabilize downstream dependencies.

How does the dry-run mode affect phase execution?

When invoked with --dry-run, the installer still executes all phases sequentially and updates the INSTALL_PHASE variable, but underlying system commands are replaced with no-op or echo-only implementations. This allows operators to preview the installation flow, verify variable expansion, and validate phase logic without modifying system state or consuming resources.

Where are the ODS phase scripts located?

All phase scripts reside in the ods/installers/phases/ directory, named according to execution order (e.g., 01-preflight.sh, 02-detection.sh, 13-summary.sh). The orchestrator sources these files using absolute paths constructed from $SCRIPT_DIR, ensuring reliable execution regardless of the current working directory.

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