# Dream Server Installer Architecture: Main Components and Design

> Explore the Dream Server installer architecture. Discover its modular Bash orchestrator with pure-function libraries and imperative install phases for Linux, macOS, and Windows.

- Repository: [Light Heart Labs/DreamServer](https://github.com/Light-Heart-Labs/DreamServer)
- Tags: architecture
- Published: 2026-05-18

---

**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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install-core.sh))

The [`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/constants.sh)** – Global configuration constants for default paths and environment variables.
- **[`logging.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/logging.sh)** – Unified logging interface providing `log`, `warn`, and `error` helper functions.
- **[`ui.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/ui.sh)** – Terminal interaction utilities including progress bars and interactive prompts.
- **[`sudo.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/sudo.sh)** – Safe privilege escalation handling with validation.
- **[`detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/detection.sh)** – Operating system, GPU, and Linux distribution detection logic.
- **[`host-arch.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/host-arch.sh)** – Architecture detection helpers for x86 and ARM platforms.
- **[`tier-map.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/tier-map.sh)** – Hardware-to-tier mapping logic that assigns Dream Server performance tiers.
- **[`docker-images.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-images.sh)** – Container image pull and build orchestration functions.
- **[`compose-select.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose-select.sh) & [`compose-failure-report.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose-failure-report.sh)** – Docker Compose overlay selection and diagnostic reporting.
- **[`readiness-summary.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/readiness-summary.sh)** – Post-install health summary generation.
- **[`packaging.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/packaging.sh)** – Optional asset packaging steps such as model zip preparation.
- **[`python-runtime.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/python-runtime.sh)** – Python environment validation and setup.
- **[`progress.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/progress.sh)** – Generic progress-bar implementation for long-running operations.
- **[`background-tasks.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/01-preflight.sh)** – System sanity checks including disk space and OS version validation.
2. **[`02-detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/02-detection.sh)** – GPU, OS, and hardware tier detection; populates the `$TIER` variable.
3. **[`03-features.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/03-features.sh)** – Resolution of optional services (voice, RAG, etc.) based on user flags.
4. **[`04-requirements.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/04-requirements.sh)** – Installation of OS packages and Python dependencies.
5. **[`05-docker.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/05-docker.sh)** – Docker installation (if absent) and daemon configuration.
6. **[`06-directories.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/06-directories.sh)** – Creation of the `$INSTALL_DIR` layout and `.env` file generation.
7. **[`07-devtools.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/07-devtools.sh)** – Installation of optional developer tools (git, curl, jq).
8. **[`08-images.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/08-images.sh)** – Pulling or building container images for all enabled services.
9. **[`09-offline.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/09-offline.sh)** – Adjustments for fully offline installations (M1-only mode).
10. **[`10-amd-tuning.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/10-amd-tuning.sh)** – AMD-specific GPU performance optimizations.
11. **[`11-services.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/11-services.sh)** – Docker Compose stack initialization and health-check waiting.
12. **[`12-health.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/12-health.sh)** – Comprehensive health-check suite execution and reporting.
13. **[`13-summary.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/dispatch.sh)** – Centralizes CLI argument parsing and command dispatch logic used by the top-level [`install.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install.sh) entry point.
- **[`installers/common.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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:

```bash

# 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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install.sh) script ultimately delegates to [`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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:

```bash

# 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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install-core.sh).

## Summary

The Dream Server installer architecture consists of five primary components:

- **[`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install-macos.sh)) that reuse core libraries while handling platform differences.
- **Dispatch utilities** – Shared argument parsing and initialization logic in [`dispatch.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dispatch.sh) and [`common.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install-core.sh) in Dream Server?

[`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/01-preflight.sh) or [`06-directories.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/06-directories.sh).