How to Preview the Resolved Docker Compose Stack Without Starting Services in DreamServer

Yes. DreamServer includes the resolve-compose-stack.sh script that builds the exact list of Docker Compose files for your configuration and outputs them without launching any containers.

DreamServer's modular architecture dynamically assembles Docker Compose stacks based on your GPU backend, installed extensions, and configuration tier. The dream-server/scripts/resolve-compose-stack.sh utility allows you to preview the resolved Docker Compose stack without starting the services, providing full visibility into service merging and extension loading before deployment.

Using the resolve-compose-stack.sh Script

The core resolver is located at dream-server/scripts/resolve-compose-stack.sh. This script performs file discovery and string manipulation only—it never executes docker compose up or interacts with the Docker daemon, making it completely safe to run in any environment.

When invoked, the script parses your installer options (tier, GPU backend, profile overlays) and discovers:

• The core compose file (docker-compose.yml or docker-compose.base.yml plus GPU-specific overlays)
• Enabled extension compose fragments from extensions/services/*/manifest.yaml
• User-installed extensions under data/user-extensions
• Optional docker-compose.override.yml if present

Basic File Discovery

To see the raw -f flag list that Docker Compose would use, run the script without arguments:

./dream-server/scripts/resolve-compose-stack.sh

This outputs the files in merge order:

-f docker-compose.base.yml -f docker-compose.nvidia.yml -f extensions/services/tts/compose.yaml

Exporting Environment Variables with --env

To capture the resolved files as shell variables, invoke the script with the --env flag. According to the DreamServer source code, argument handling at lines 34-38 detects this switch and sets env_mode=true, triggering the conditional block at lines 600-608 that exports three environment variables without starting services:

eval $(./dream-server/scripts/resolve-compose-stack.sh --env)

After execution, the following variables are available:

• COMPOSE_PRIMARY_FILE – The file Docker treats as the primary compose file
• COMPOSE_FILE_LIST – A comma-separated list of all resolved files
• COMPOSE_FLAGS – A ready-to-use string formatted as -f file1.yml -f file2.yml …

Inspect these variables to verify your stack composition:

echo "$COMPOSE_PRIMARY_FILE"

# → docker-compose.nvidia.yml

echo "$COMPOSE_FILE_LIST"

# → docker-compose.base.yml,docker-compose.nvidia.yml,extensions/services/tts/compose.yaml

echo "$COMPOSE_FLAGS"

# → -f docker-compose.base.yml -f docker-compose.nvidia.yml -f extensions/services/tts/compose.yaml

Viewing the Fully Merged Configuration

To preview the resolved Docker Compose stack without starting the services, pipe the script's output into docker compose config. This renders the final merged YAML that Docker Compose would use, including all services, networks, and ports:

Using the exported variables:

docker compose $COMPOSE_FLAGS config

Or as a one-liner without exporting variables:

docker compose $(./dream-server/scripts/resolve-compose-stack.sh) config

This command displays the fully resolved configuration, allowing you to validate extension loading, environment variables, and service dependencies before any containers are created.

How the Resolution Logic Works

The resolve-compose-stack.sh script assembles the file list in the exact order Docker Compose merges them. It reads extension manifests to locate compose fragments and conditionally includes GPU-specific overlays—such as docker-compose.nvidia.yml, docker-compose.amd.yml, docker-compose.cpu.yml, or docker-compose.apple.yml—based on your system configuration. Because the script only performs file discovery and string manipulation, execution is instantaneous and carries no risk of starting containers.

Summary

• Use dream-server/scripts/resolve-compose-stack.sh to resolve the complete Docker Compose file list without starting services.
• Add the --env flag to export COMPOSE_PRIMARY_FILE, COMPOSE_FILE_LIST, and COMPOSE_FLAGS variables for programmatic inspection.
• Run docker compose $COMPOSE_FLAGS config to view the fully merged YAML configuration before deployment.
• The script parses manifests from extensions/services/*/manifest.yaml and user extensions in data/user-extensions, ensuring accurate preview of your complete stack.

Frequently Asked Questions

Does previewing the stack require Docker to be running?

No. The resolve-compose-stack.sh script performs file discovery and string concatenation without interacting with the Docker daemon. Only when you run docker compose config to view the merged YAML does Docker need to be available, and even then, no containers are started or modified.

Can I see which extensions are included in the resolved stack?

Yes. Inspect the COMPOSE_FILE_LIST variable after running the script with --env. The list includes full paths to extension compose files from extensions/services/ and data/user-extensions, revealing exactly which service fragments are active in your configuration.

What GPU-specific files does the resolver include?

The resolver conditionally selects from docker-compose.nvidia.yml, docker-compose.amd.yml, docker-compose.cpu.yml, or docker-compose.apple.yml based on your detected GPU backend and installer tier settings. These overlays are prepended to the file list according to the merge order defined in the script's logic at lines 600-608.

How do I verify the final configuration before running docker compose up?

Run docker compose $(./dream-server/scripts/resolve-compose-stack.sh) config to render the complete merged configuration. This outputs the final YAML that Docker Compose would use, allowing you to verify services, networks, volumes, and environment variables without starting any services.

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