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

> Preview your Docker Compose stack without starting services using DreamServer's resolve-compose-stack.sh script. See the exact configuration before deployment.

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

---

**Yes.** DreamServer includes the [`resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.yml) or [`docker-compose.base.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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:

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

```

This outputs the files in merge order:

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

```bash
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:

```bash
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:

```bash
docker compose $COMPOSE_FLAGS config

```

Or as a one-liner without exporting variables:

```bash
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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](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), [`docker-compose.cpu.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.cpu.yml), or [`docker-compose.apple.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](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), [`docker-compose.cpu.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.cpu.yml), or [`docker-compose.apple.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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.