Dream Server Installation Process: A 13-Phase Technical Guide

The Dream Server installation process consists of 13 sequential phases orchestrated by 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, 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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:

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

For debugging or customization, inspect specific phase logic:

# 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:

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 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 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 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 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 identifies GPU topology and vendor (NVIDIA or AMD), while 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.

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