What Is the INSTALL_PHASE Variable in the Dream Server Installer?

The INSTALL_PHASE variable tracks the current installation stage, enables precise error reporting, and supports resumable installations in the Dream Server orchestrator.

In the Light-Heart-Labs/DreamServer repository, the INSTALL_PHASE variable serves as the central state tracker for the bash-based installation orchestrator. Found in dream-server/install-core.sh, this exported string coordinates how the installer progresses through sequential phases, handles fatal errors via traps, and allows users to resume interrupted setups without starting from scratch.

Core Functions of the INSTALL_PHASE Variable

Phase Tracking

Before each installer step executes, the orchestrator assigns a descriptive name to INSTALL_PHASE and then sources the corresponding phase script. This makes the current stage explicit throughout the execution flow. According to the project documentation in CLAUDE.md, the orchestrator sets this variable before each phase specifically for error reporting and state management.

In install-core.sh (lines 247-263), the sequential sourcing logic updates INSTALL_PHASE immediately before invoking each phase script:

INSTALL_PHASE="02-detection"
source "$SCRIPT_DIR/installers/phases/02-detection.sh"

INSTALL_PHASE="05-docker"
source "$SCRIPT_DIR/installers/phases/05-docker.sh"

This pattern ensures that any script sourced during installation can query $INSTALL_PHASE to determine the current operational context.

Error Reporting

The INSTALL_PHASE variable enables granular error localization through the cleanup_on_error trap defined early in install-core.sh (lines 22-28). Because the installer runs with set -euo pipefail (aborting on the first error), the trap uses ${INSTALL_PHASE} to print a clear, user-friendly message identifying exactly which phase caused the abort.

When a command fails inside a phase, the handler outputs:

[ERROR] Installation failed during phase: 05-docker
Log file: /tmp/dream-server-install.log

This eliminates guesswork by telling users precisely where to look for the underlying problem, whether it occurred during preflight checks, dependency detection, or Docker setup.

Resumable Installations

Because INSTALL_PHASE is exported, the variable persists across script invocations and enables partial installation recovery. If the installer exits unexpectedly, the exported state allows subsequent runs to detect a partially-completed installation and resume from the last successful phase rather than restarting from the beginning.

You can verify the current phase from any sourced script by checking the variable:

echo "Running in phase: $INSTALL_PHASE"

Implementation Details

The variable is initialized early in install-core.sh and updated throughout the orchestration loop. The strict error handling combined with phase tracking creates a robust installation flow that handles failures gracefully while providing actionable feedback.

Key implementation notes from the source:

• File: dream-server/install-core.sh defines and manages the variable lifecycle
• Scope: Exported to ensure visibility in subshells and sourced scripts
• Error Hook: The cleanup_on_error function references ${INSTALL_PHASE} to generate failure messages

Summary

• Phase Tracking: INSTALL_PHASE stores the current installation stage (e.g., 02-detection, 05-docker) before sourcing phase-specific scripts in install-core.sh
• Error Localization: The cleanup_on_error trap uses the variable to report exactly which phase failed when set -euo pipefail triggers an abort
• Resumability: Exported state allows the installer to resume from the last successful phase instead of starting over from scratch
• Documentation: The architectural role is documented in CLAUDE.md and implemented across lines 22-28 and 247-263 of the main orchestrator

Frequently Asked Questions

What happens if INSTALL_PHASE is not set before a phase runs?

If INSTALL_PHASE is unset or empty, the cleanup_on_error trap will print an empty phase name in the error message, making debugging significantly harder. The install-core.sh orchestrator explicitly sets this variable before every source call to ensure accurate error reporting.

Can I manually set INSTALL_PHASE to skip to a specific phase?

While technically possible since the variable is exported, manually altering INSTALL_PHASE to skip phases is not recommended. The installer assumes all previous phases completed successfully, and skipping validation or dependency detection steps will likely leave the system in an inconsistent state.

Where is INSTALL_PHASE stored if the installation script exits unexpectedly?

INSTALL_PHASE exists only as a shell environment variable during script execution. It is not persisted to disk by default. However, because it is exported, if you run the installer again in the same shell session (or if the script logs/exported it before exit), the value remains available for resumability logic.

How does the cleanup_on_error trap access INSTALL_PHASE without explicit passing?

The trap is defined in the same shell scope as the variable assignments in install-core.sh. Since INSTALL_PHASE is exported and the trap executes within the same shell process (not a subshell), it has direct access to the current value of ${INSTALL_PHASE} via standard variable expansion when the error occurs.

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