What Is resolve-compose-stack.sh in DreamServer?

The 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 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, 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, docker-compose.amd.yml, or 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 to check if the service is marked as enabled: true, then collects the corresponding 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. 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:

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), the script is sourced to prepare the environment before containers are started:

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 defining the Docker service
3. Set enabled: true in the extension's manifest.yaml

On the next install run, resolve-compose-stack.sh automatically discovers and includes the new service in docker-compose.generated.yml.

Key Files in the Resolution Pipeline

• dream-server/scripts/resolve-compose-stack.sh: Core resolver that orchestrates the merge process
• 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 dynamically generates 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 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 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, docker-compose.amd.yml, or 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 (with enabled: true) and a 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.

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