# Dream Server Installation Process: A 13-Phase Technical Guide

> Explore the 13-phase Dream Server installation process. This technical guide covers preflight checks to post-install health, detailed in modular Bash scripts. Install Dream Server efficiently.

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

---

**The Dream Server installation process consists of 13 sequential phases orchestrated by [`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install-core.sh), ranging from preflight system validation to post-install health checks, each implemented as a modular Bash script in `dream-server/installers/phases/`.**

The Dream Server installation process in the Light-Heart-Labs/DreamServer repository follows a strict linear pipeline designed for reliability across diverse hardware configurations. Unlike monolithic installers, this architecture executes discrete phases sequentially, allowing granular error tracking and modular customization without touching core orchestration logic.

## Architecture of the Dream Server Installation Process

The orchestration engine resides in [`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install-core.sh), which manages execution flow by setting the `INSTALL_PHASE` environment variable for precise error reporting and rendering progress indicators via `dream_progress`. Each phase operates as an independent Bash module within `dream-server/installers/phases/`, enabling developers to modify specific setup stages or inject custom validation logic without risking the stability of the broader installation pipeline.

## The 13 Installation Phases Explained

### Phase 01 – Preflight: System Validation

[`01-preflight.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/01-preflight.sh) performs mandatory safety checks before any filesystem modifications occur. It verifies **non-root execution**, detects the host operating system, and validates required tools including `curl` and `jq`. The script checks for optional utilities like `rsync`, inspects firewall status, examines the installation directory filesystem capacity, and specifically validates Docker Desktop file-sharing configuration to prevent runtime permission errors on macOS and Windows hosts.

### Phase 02 – Detection: Hardware Profiling

[`02-detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/02-detection.sh) analyzes system capabilities to determine optimal configuration parameters. It measures available **RAM**, **disk capacity**, and **GPU topology** (including multi-GPU setups). Based on these metrics, the phase assigns a **performance tier** and resolves the appropriate Docker Compose overlay and model profile. The script handles cloud-mode shortcuts and validates NVIDIA driver installations when discrete GPUs are detected.

### Phase 03 – Features: Service Configuration

[`03-features.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/03-features.sh) presents an interactive menu (or accepts non-interactive flags) to enable optional services such as **voice processing**, **workflows**, **RAG**, **Hermes**, **OpenClaw**, **ComfyUI**, and **Langfuse**. This phase synchronizes extension [`compose.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose.yaml) files, refreshes compose flags, and generates **GPU-assignment JSON** configurations for both single and multi-GPU deployments, ensuring containers are pinned to specific graphics devices.

### Phase 04 – Requirements: Dependency Verification

[`04-requirements.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/04-requirements.sh) audits the environment for mandatory runtime packages including Docker, Docker Compose, and Python, ensuring they meet minimum version constraints before the installer attempts to pull container images.

### Phase 05 – Docker: Engine Preparation

[`05-docker.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/05-docker.sh) verifies that the Docker daemon is active, pulls base images, and validates critical configuration parameters such as the **cgroup driver** to ensure container compatibility with the host kernel.

### Phase 06 – Directories: Filesystem Setup

[`06-directories.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/06-directories.sh) creates the installation directory hierarchy and generates a `.env` file containing cryptographically secure secrets. It immediately restricts these sensitive files with `chmod 600` to prevent credential exposure to non-privileged users.

### Phase 07 – Devtools: Development Environment

[`07-devtools.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/07-devtools.sh) installs optional build utilities including `git`, `make`, and `npm`, which are required for compiling extensions from source or importing custom machine learning models.

### Phase 08 – Images: Container Acquisition

[`08-images.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/08-images.sh) pulls all required container images from registries, optionally builds custom images from local Dockerfiles, and verifies image digests to ensure supply chain integrity before deployment.

### Phase 09 – Offline: Air-Gapped Support

[`09-offline.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/09-offline.sh) implements fallback mechanisms for environments without internet connectivity, utilizing cached container images and local package repositories when external resources are unavailable.

### Phase 10 – AMD Tuning: GPU Optimization

[`10-amd-tuning.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/10-amd-tuning.sh) applies AMD-specific driver optimizations, loads necessary kernel modules such as `amdgpu`, and configures the system for ROCm compatibility on AMD GPU hardware.

### Phase 11 – Services: Stack Orchestration

[`11-services.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/11-services.sh) launches the Docker Compose stack, monitors health endpoints for dependency readiness, and logs accessible URLs for web interfaces and API endpoints to standard output.

### Phase 12 – Health: Operational Verification

[`12-health.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/12-health.sh) executes comprehensive post-installation probes against critical services including the dashboard and LLM server, confirming that all containers report healthy status before marking the installation complete.

### Phase 13 – Summary: User Guidance

[`13-summary.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/13-summary.sh) outputs a formatted report containing installation status, dashboard URLs, API endpoint locations, and concrete next steps for the administrator.

## Executing and Debugging the Installation

To initiate the complete Dream Server installation process:

```bash
cd dream-server
./install.sh   # Invokes install-core.sh → runs phases 01–13 sequentially

```

For debugging or customization, inspect specific phase logic:

```bash

# View the preflight phase implementation

cat dream-server/installers/phases/01-preflight.sh

```

Advanced users can source individual phases to set environment variables without executing the full pipeline:

```bash
source dream-server/installers/phases/02-detection.sh
echo "Detected tier: $TIER"
echo "GPU Backend: $GPU_BACKEND"

```

## Summary

- The Dream Server installation process comprises **13 sequential phases** orchestrated by [`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install-core.sh) in the Light-Heart-Labs/DreamServer repository.
- Phases 01–03 handle **system validation, hardware detection, and feature selection** through interactive menus that generate GPU-assignment configurations.
- Phases 04–10 manage **dependency resolution, Docker configuration, directory setup, and GPU-specific tuning** for both NVIDIA and AMD hardware, including offline support mechanisms.
- Phases 11–13 perform **service orchestration, health verification, and final summary reporting** to confirm operational status of the dashboard and LLM endpoints.
- Each phase resides in `dream-server/installers/phases/` as a modular Bash script, enabling surgical modifications without disrupting the core orchestration logic or progress tracking.

## Frequently Asked Questions

### How do I run only specific phases of the Dream Server installation?

While [`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install-core.sh) is designed to execute all 13 phases sequentially for consistency, you can manually source individual phase scripts from `dream-server/installers/phases/` to set environment variables or execute specific logic. However, this bypasses the error handling and state management provided by the main orchestrator.

### What happens if a phase fails during the Dream Server installation process?

The installer sets the `INSTALL_PHASE` environment variable before executing each stage. If a phase exits with a non-zero status, [`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install-core.sh) captures the failure context and terminates the pipeline, allowing you to inspect logs for the specific phase that failed without partial system modifications contaminating subsequent stages.

### Does the Dream Server installer support offline environments?

Yes, phase [`09-offline.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/09-offline.sh) specifically handles air-gapped deployments by implementing fallback mechanisms that utilize cached container images and local package repositories when internet connectivity is unavailable, ensuring the Dream Server installation process completes in restricted network environments.

### How does the installer handle different GPU vendors?

Phase [`02-detection.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/02-detection.sh) identifies GPU topology and vendor (NVIDIA or AMD), while [`10-amd-tuning.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/10-amd-tuning.sh) applies vendor-specific optimizations. For NVIDIA hardware, the detection phase validates driver compatibility; for AMD systems, the tuning phase loads necessary kernel modules and configures ROCm support based on the detected hardware profile.