# What Is the INSTALL_PHASE Variable in the Dream Server Installer?

> Understand the INSTALL_PHASE variable in the Dream Server installer. Track installation stages, get precise errors, and enable resumable installs.

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

---

**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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/CLAUDE.md), the orchestrator sets this variable before each phase specifically for error reporting and state management.

In [`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install-core.sh) (lines 247-263), the sequential sourcing logic updates `INSTALL_PHASE` immediately before invoking each phase script:

```bash
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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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:

```text
[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:

```bash
echo "Running in phase: $INSTALL_PHASE"

```

## Implementation Details

The variable is initialized early in [`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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.