# What Is resolve-compose-stack.sh in DreamServer? > Discover the purpose of resolve-compose-stack.sh in DreamServer. This script dynamically builds your Docker Compose configuration by merging base services and extensions. - Repository: [Light Heart Labs/DreamServer](https://github.com/Light-Heart-Labs/DreamServer) - Tags: internals - Published: 2026-05-18 --- **The [`resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/resolve-compose-stack.sh) script is a compose-stack resolver that dynamically assembles the final Docker Compose configuration by merging base services, GPU-specific overlays, and enabled extension fragments into a single [`docker-compose.generated.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.generated.yml) file.** The DreamServer project employs a modular approach to container orchestration, allowing the platform to adapt to different hardware configurations and optional services. At the heart of this flexibility lies [`scripts/resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/scripts/resolve-compose-stack.sh), a shell script responsible for resolving the complete Docker Compose stack at install time. This script eliminates manual editing of compose files by automatically detecting hardware capabilities and aggregating service definitions from multiple sources. ## How resolve-compose-stack.sh Works ### Hardware Detection and GPU Overlay Selection The script begins by detecting the system's hardware tier using the installer's tier-map utilities. Based on this detection, it selects the appropriate GPU overlay file—[`docker-compose.nvidia.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.nvidia.yml), [`docker-compose.amd.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.amd.yml), or [`docker-compose.apple.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.apple.yml)—to layer on top of the base configuration. ### Extension Discovery via Manifest Parsing Next, the script scans the `extensions/services/` directory for enabled extensions. It reads each service's [`manifest.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/manifest.yaml) to check if the service is marked as `enabled: true`, then collects the corresponding [`compose.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose.yaml) files from matching extension directories. This allows DreamServer to include optional services like Ollama or LLM-Worker only when explicitly activated. ### Merging Compose Fragments With all components identified, the script constructs an ordered file list: **base compose** → **GPU overlay** → **extension files** → **user overrides**. It then executes `docker compose -f … config` to merge these fragments and writes the output to [`docker-compose.generated.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.generated.yml). Finally, it exports the `COMPOSE_FILE` environment variable pointing to this generated file, ensuring downstream commands use the resolved stack. ## Manual Execution and Debugging You can run the resolver independently to inspect or debug the generated configuration: ```bash cd dream-server ./scripts/resolve-compose-stack.sh # Generates docker-compose.generated.yml cat docker-compose.generated.yml # Inspect the final merged stack ``` ## Integration with the DreamServer Installer Within the main installation workflow (typically [`install-core.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/install-core.sh)), the script is sourced to prepare the environment before containers are started: ```bash source "./scripts/resolve-compose-stack.sh" docker compose -f "$COMPOSE_FILE" up -d ``` This pattern ensures that `docker compose up` receives the fully resolved, hardware-specific configuration without manual file concatenation. ## Extending the Stack with Custom Services To add a new extension without modifying core files: 1. Create a directory under `extensions/services/my-service/` 2. Add a [`compose.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose.yaml) defining the Docker service 3. Set `enabled: true` in the extension's [`manifest.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/manifest.yaml) On the next install run, [`resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/resolve-compose-stack.sh) automatically discovers and includes the new service in [`docker-compose.generated.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.generated.yml). ## Key Files in the Resolution Pipeline - **[`dream-server/scripts/resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/scripts/resolve-compose-stack.sh)**: Core resolver that orchestrates the merge process - **[`dream-server/docker-compose.base.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/docker-compose.base.yml)**: Core services required for every installation - **`docker-compose.{amd,nvidia,apple}.yml`**: GPU-specific overlays for AMD, NVIDIA, or Apple Silicon - **`extensions/services/*/manifest.yaml`**: Metadata files indicating which extensions are enabled - **`extensions/services/*/compose.yaml`**: Service-specific fragments merged into the final stack ## Summary - [`resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/resolve-compose-stack.sh) dynamically generates [`docker-compose.generated.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.generated.yml) by merging multiple compose fragments - The script detects hardware capabilities to select the correct GPU overlay (AMD, NVIDIA, or Apple) - It automatically includes enabled extensions by scanning [`manifest.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/manifest.yaml) files in `extensions/services/` - The final merged configuration is exported via the `COMPOSE_FILE` environment variable for downstream Docker commands - This architecture keeps DreamServer modular, allowing hardware-aware deployment without manual compose file editing ## Frequently Asked Questions ### What is the output file of resolve-compose-stack.sh? The script generates [`docker-compose.generated.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.generated.yml) in the dream-server directory. This file contains the fully merged Docker Compose configuration ready for deployment, incorporating base services, GPU overlays, and any enabled extensions. ### How does resolve-compose-stack.sh detect which GPU overlay to use? The script calls the installer's tier-map utilities to detect the hardware tier, then selects the corresponding overlay file ([`docker-compose.nvidia.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.nvidia.yml), [`docker-compose.amd.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.amd.yml), or [`docker-compose.apple.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.apple.yml)) based on the detected GPU type. ### Can I run resolve-compose-stack.sh independently of the installer? Yes. You can execute the script manually from the `dream-server` directory to generate or debug the compose stack. This is useful for inspecting how extensions and GPU overlays are merged before starting containers. ### How do I add a new service to the DreamServer stack? Create a new extension directory under `extensions/services/` containing both a [`manifest.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/manifest.yaml) (with `enabled: true`) and a [`compose.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose.yaml) defining your service. The resolver will automatically include it in the generated stack on the next run without requiring changes to the base compose files.