Dream Server Installer Architecture: Main Components and Design

The Dream Server installer is a modular, staged Bash orchestrator that cleanly separates pure-function libraries from imperative install phases, coordinated by install-core.sh to support Linux, macOS, and Windows deployment.

The open-source Dream Server project from Light-Heart-Labs/DreamServer implements its installation logic as a modular Bash architecture rather than a monolithic script. This design separates side-effect-free utility functions from stateful installation steps, enabling isolated testing, cross-platform reuse, and clear error attribution when failures occur.

Core Orchestrator (install-core.sh)

The install-core.sh file serves as the central entry point and phase driver for the entire installation process.

This script establishes strict execution semantics by setting set -euo pipefail immediately on startup, ensuring that undefined variables, failed commands, and pipeline errors terminate execution rather than continue silently. It registers a failure trap that reports the active INSTALL_PHASE variable when crashes occur, making debugging straightforward.

The orchestrator loads the entire utility library by sourcing all files from installers/lib/ (lines 71‑84), then executes installation phases sequentially by setting the INSTALL_PHASE environment variable and sourcing the corresponding phase script from installers/phases/ (lines 47‑66).

Pure-Function Library Layer (installers/lib/*.sh)

Located in installers/lib/, these modules contain re-usable, side-effect-free Bash functions that implement business logic without modifying system state. Because they avoid side effects, they can be unit-tested in isolation and safely reused by multiple phases or platform-specific installers.

The library collection includes:

• constants.sh – Global configuration constants for default paths and environment variables.
• logging.sh – Unified logging interface providing log, warn, and error helper functions.
• ui.sh – Terminal interaction utilities including progress bars and interactive prompts.
• sudo.sh – Safe privilege escalation handling with validation.
• detection.sh – Operating system, GPU, and Linux distribution detection logic.
• host-arch.sh – Architecture detection helpers for x86 and ARM platforms.
• tier-map.sh – Hardware-to-tier mapping logic that assigns Dream Server performance tiers.
• docker-images.sh – Container image pull and build orchestration functions.
• compose-select.sh & compose-failure-report.sh – Docker Compose overlay selection and diagnostic reporting.
• readiness-summary.sh – Post-install health summary generation.
• packaging.sh – Optional asset packaging steps such as model zip preparation.
• python-runtime.sh – Python environment validation and setup.
• progress.sh – Generic progress-bar implementation for long-running operations.
• background-tasks.sh – Asynchronous task execution utilities.

These libraries are sourced once during orchestrator initialization and remain available throughout the installation lifecycle.

Sequential Install Phases (installers/phases/*.sh)

Each phase script in installers/phases/ performs imperative, stateful actions such as creating directories, installing system packages, or starting services. The orchestrator executes them in strict numerical order to respect dependencies, setting INSTALL_PHASE before sourcing each script:

1. 01-preflight.sh – System sanity checks including disk space and OS version validation.
2. 02-detection.sh – GPU, OS, and hardware tier detection; populates the $TIER variable.
3. 03-features.sh – Resolution of optional services (voice, RAG, etc.) based on user flags.
4. 04-requirements.sh – Installation of OS packages and Python dependencies.
5. 05-docker.sh – Docker installation (if absent) and daemon configuration.
6. 06-directories.sh – Creation of the $INSTALL_DIR layout and .env file generation.
7. 07-devtools.sh – Installation of optional developer tools (git, curl, jq).
8. 08-images.sh – Pulling or building container images for all enabled services.
9. 09-offline.sh – Adjustments for fully offline installations (M1-only mode).
10. 10-amd-tuning.sh – AMD-specific GPU performance optimizations.
11. 11-services.sh – Docker Compose stack initialization and health-check waiting.
12. 12-health.sh – Comprehensive health-check suite execution and reporting.
13. 13-summary.sh – Final URL reporting and "ready" message display (fails harmlessly if skipped).

This staged approach ensures that prerequisite steps (such as Docker installation) complete before dependent steps (such as image pulling) begin.

Platform-Specific Wrappers

While the core architecture targets Linux, Windows and macOS use thin wrapper scripts that import the same libraries and phases while adapting platform-specific differences:

• Windows: installers/windows/install-windows.ps1 and dream.ps1 provide PowerShell-based entry points that handle Windows-specific path conventions and service management.
• macOS: installers/macos/install-macos.sh sources the standard libraries but adjusts for macOS-specific Docker Desktop requirements and compose file locations.

These wrappers maintain architectural consistency across operating systems, following DRY (Don't Repeat Yourself) principles by reusing the installers/lib/ and installers/phases/ directories rather than duplicating logic.

Dispatch and Extension Utilities

Additional architectural components support command-line dispatch and shared initialization:

• installers/dispatch.sh – Centralizes CLI argument parsing and command dispatch logic used by the top-level install.sh entry point.
• installers/common.sh – Contains shared initialization utilities such as path resolution routines used by multiple entry points.

Practical Implementation Examples

Running the Standard Installation

Execute the following commands to run a complete Dream Server installation on Linux:

# Clone the repository and enter the installation directory

git clone https://github.com/Light-Heart-Labs/DreamServer.git
cd DreamServer/dream-server

# Interactive installation with default settings

./install.sh

# Non-interactive installation with all optional services enabled

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

The install.sh script ultimately delegates to install-core.sh, which loads libraries and executes each phase in the prescribed order.

Adding a Custom Installation Phase

To extend the installer with a backup phase that runs before preflight, create the phase file and register it in the orchestrator:

# Create the new phase file

cat > installers/phases/01-create-backup.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
log "Creating backup of existing install directory..."
if [[ -d "$INSTALL_DIR" ]]; then
  cp -a "$INSTALL_DIR" "${INSTALL_DIR}.bak_$(date +%Y%m%d%H%M%S)"
fi
EOF

# Register in install-core.sh by adding after the preflight phase:

# INSTALL_PHASE="01-create-backup"; source "$SCRIPT_DIR/installers/phases/01-create-backup.sh"

Because the phase follows the established pattern of setting INSTALL_PHASE before sourcing, it automatically integrates with the error-handling trap and progress reporting UI defined in install-core.sh.

Summary

The Dream Server installer architecture consists of five primary components:

• install-core.sh – The central orchestrator enforcing set -euo pipefail and driving phase execution via the INSTALL_PHASE variable.
• installers/lib/*.sh – Fourteen pure-function libraries providing side-effect-free utilities for logging, detection, and Docker management.
• installers/phases/*.sh – Thirteen imperative phase scripts executed sequentially to perform system modifications.
• Platform wrappers – OS-specific entry points (install-windows.ps1, install-macos.sh) that reuse core libraries while handling platform differences.
• Dispatch utilities – Shared argument parsing and initialization logic in dispatch.sh and common.sh.

This separation between functional libraries and imperative phases, coordinated by a strict orchestrator, enables robust cross-platform deployment with clear error attribution and extension points.

Frequently Asked Questions

What is the role of install-core.sh in Dream Server?

install-core.sh acts as the central entry point and execution engine for the Dream Server installer. It sets strict error handling via set -euo pipefail, sources all utility libraries from installers/lib/, and drives the sequential execution of installation phases by setting the INSTALL_PHASE environment variable before sourcing each phase script. According to the Light-Heart-Labs/DreamServer source code, this orchestrator runs on lines 47‑66 to execute phases and lines 71‑84 to load libraries.

How do the installer phases maintain execution order?

The installer maintains execution order through numerical prefixes (01 through 13) and explicit sourcing within install-core.sh. The orchestrator sets the INSTALL_PHASE variable to the current phase name before sourcing the corresponding file from installers/phases/*.sh, ensuring that prerequisites such as Docker installation (phase 05) complete before dependent steps like image pulling (phase 08) begin. This staged approach prevents race conditions and dependency violations.

Can I run the Dream Server installer on Windows or macOS?

Yes, the Dream Server supports Windows and macOS through platform-specific wrapper scripts. Windows installations use installers/windows/install-windows.ps1 or dream.ps1, while macOS uses installers/macos/install-macos.sh. These wrappers source the same installers/lib/ libraries and installers/phases/ scripts used by the Linux installer, adapting only platform-specific elements such as path handling or Docker Desktop configuration, as implemented in the Light-Heart-Labs/DreamServer repository.

How can I add custom logic to the Dream Server installation process?

You can extend the installer by adding new phase scripts to installers/phases/ following the naming convention NN-descriptive-name.sh (where NN is a two-digit number). Each phase must set set -euo pipefail and conform to the pattern of setting INSTALL_PHASE before performing actions. Register the new phase in install-core.sh by adding a line that sets INSTALL_PHASE and sources your script, placing it in the numerical sequence where it should execute relative to existing phases such as 01-preflight.sh or 06-directories.sh.

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