What Is the Purpose of the install-core.sh Script in ODS?

The install-core.sh script serves as the central orchestrator for the Osmantic ODS installer, initializing the Bash environment, parsing command-line flags, sourcing utility libraries, and executing sequential installation phases to deploy the full ODS stack.

The install-core.sh script is the core execution engine behind the Osmantic ODS (Open Data Stack) deployment process. Located at ods/install-core.sh in the repository, this script coordinates every aspect of system installation from strict environment initialization through final health verification. Understanding its architecture is essential for customizing deployments, troubleshooting failures, or extending the installer for new hardware tiers.

Core Responsibilities of the install-core.sh Orchestrator

The script functions as a deterministic coordinator that transforms user inputs into a complete system deployment. According to the Osmantic/ODS source code, it manages seven critical responsibilities:

Environment Initialization with Strict Error Handling

At lines 17–38 of ods/install-core.sh, the script establishes defensive Bash settings using set -euo pipefail to ensure the installer exits immediately on errors, treats unset variables as errors, and catches failures in piped commands. It registers a cleanup_on_error trap that logs the failed phase, prints recovery instructions, and preserves the original exit status code. This architecture guarantees that interruptions—whether from failures or user cancellations—are handled gracefully without leaving the system in an inconsistent state.

Loading Pure-Function Libraries

The orchestrator sources all reusable, side-effect-free Bash modules from the installers/lib/ directory (lines 68–90). These libraries include:

• constants.sh – Global configuration values and path definitions
• logging.sh – Structured output formatting and verbosity controls
• detection.sh – Hardware and operating system identification functions
• tier-map.sh – GPU tier classification and capability mapping

By loading these dependencies before argument processing, install-core.sh ensures all helper functions are available for subsequent detection and installation phases.

Command-Line Argument Parsing

Between lines 96–123, the script interprets flags that control installation behavior. It processes options such as --dry-run, --tier, --voice, --all, and --non-interactive, populating variables that determine which services are enabled. This parsing logic allows a single installer to adapt to diverse deployment scenarios—from minimal headless installations to full-featured stacks with voice recognition, RAG pipelines, and Langfuse observability.

System Detection and Hardware Tier Mapping

Following argument processing, the script invokes detect_pkg_manager and related helpers at lines 16–19 to discover the host OS, available package managers, GPU capabilities, and hardware tier. This detection phase maps physical hardware characteristics to logical installation profiles, ensuring that resource-intensive services like Hermes or OpenClaw are only installed on compatible systems.

Sequential Phase Execution

The script implements a deterministic installation pipeline by setting the INSTALL_PHASE variable and sourcing phase scripts sequentially (lines 35–64). The orchestrator executes thirteen distinct phases:

1. 01-preflight.sh – Prerequisites validation
2. 02-detection.sh – Hardware profiling
3. 03-infrastructure.sh – Base services deployment
4. Through 13-summary.sh – Final verification and reporting

This phased approach ensures that infrastructure dependencies are satisfied before application services are deployed, and that health checks run only after all components are configured.

Optional Feature Configuration

Through parsed flags (lines 100–127), install-core.sh conditionally enables optional services including voice processing, workflow engines, RAG (Retrieval-Augmented Generation), Hermes, OpenClaw, and Langfuse tracing. The script evaluates hardware tiers against service requirements, automatically disabling incompatible features or prompting for resolution in interactive mode.

Practical Usage Examples

The install-core.sh script is typically invoked through the install.sh wrapper, which sets up the execution environment. Common invocation patterns include:

Basic interactive installation (default):

./install.sh

Non-interactive tier-2 deployment with voice and workflows:

./install.sh --tier 2 --voice --workflows --non-interactive

Dry-run to preview changes without system modification:

./install.sh --dry-run

Force reinstall skipping Docker prerequisite checks:

./install.sh --force --skip-docker

Fully automated installation with all optional services:

./install.sh --all --non-interactive

Integration with the ODS Installer Architecture

The install-core.sh script operates within a modular architecture that separates concerns across multiple directories:

• ods/install.sh – A thin wrapper that prepares the execution context and delegates to install-core.sh
• ods/installers/lib/ – Pure-function libraries containing reusable Bash utilities
• ods/installers/phases/ – Sequential installation steps performing actual system modifications
• ods/scripts/resolve-compose-stack.sh – Docker Compose file merger invoked by phase scripts to combine base configurations with extension overlays
• ods/.env.example – Template for environment variable configuration sourced during installation

This separation allows administrators to modify individual phases (such as 04-services.sh) or library functions (such as detection.sh) without altering the core orchestration logic.

Summary

• install-core.sh is the central orchestrator located at ods/install-core.sh that manages the entire ODS installation lifecycle
• It initializes strict Bash error handling (set -euo pipefail) and registers cleanup traps to ensure reliable failure recovery
• The script sources pure-function libraries from installers/lib/ to provide logging, detection, and tier-mapping capabilities
• It parses command-line options including --dry-run, --tier, and --all to configure installation behavior
• System detection functions identify the host OS, package manager, and GPU tier to validate hardware compatibility
• Sequential phase execution runs thirteen ordered scripts from 01-preflight.sh to 13-summary.sh for deterministic deployment
• Optional features such as voice, RAG, and Langfuse are conditionally enabled based on parsed flags and detected hardware tiers

Frequently Asked Questions

What is the difference between install.sh and install-core.sh?

The install.sh script serves as a thin entry-point wrapper that locates the ODS directory, validates basic prerequisites, and sets up the execution environment before calling install-core.sh. The install-core.sh script contains the actual orchestration logic, library loading, and phase execution. You should invoke install.sh for normal operations, while install-core.sh is designed to be called only after the environment is prepared.

Which installation phases does install-core.sh execute?

The script executes thirteen sequential phases located in ods/installers/phases/: 01-preflight.sh, 02-detection.sh, 03-infrastructure.sh, 04-services.sh, 05-webapp.sh, 06-monitoring.sh, 07-metrics.sh, 08-logging.sh, 09-backup.sh, 10-security.sh, 11-optimization.sh, 12-health.sh, and 13-summary.sh. Each phase sets the INSTALL_PHASE variable before sourcing the next script, enabling precise error tracking and recovery.

How does install-core.sh handle installation failures?

The script implements a cleanup_on_error trap function (lines 22–37) that captures the exit status of failed commands, logs the specific phase where the failure occurred, prints contextual recovery instructions, and exits with the original error code. Combined with set -euo pipefail, this ensures that partial installations are immediately halted and reported without leaving the system in an inconsistent state.

Can I run specific installation phases independently?

No, install-core.sh is designed to run all phases sequentially to maintain dependency integrity. However, you can influence which services are installed within those phases by using command-line flags such as --skip-docker, --voice, or --all. For development or debugging, you may source individual phase scripts manually after loading the required libraries from installers/lib/, though this is not recommended for production deployments.

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