# How Dream Server Manages GPU-Specific Configurations in Docker Compose

> Learn how Dream Server manages GPU-specific configurations in Docker Compose. Discover dynamic stack assembly using vendor overlays and a resolver script for efficient hardware utilization.

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

---

**Dream Server dynamically assembles hardware-specific Docker Compose stacks by merging a base configuration with vendor-specific GPU overlays using the [`scripts/resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/scripts/resolve-compose-stack.sh) resolver script.**

Dream Server supports heterogeneous hardware environments ranging from consumer GPUs to data-center accelerators. The platform handles GPU-specific configurations in Docker Compose through an intelligent file layering system that automatically selects the appropriate backend configuration based on the `--gpu-backend` argument or detected hardware tier, eliminating the need for manual YAML editing.

## The Overlay Resolution Architecture

The resolution logic is implemented in **[`scripts/resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/scripts/resolve-compose-stack.sh)**, which constructs the final `docker compose` command by layering multiple YAML files. This approach isolates hardware-specific device mappings, driver volumes, and runtime constraints from core service definitions, enabling the same codebase to support NVIDIA, AMD, Intel, and Apple Silicon GPUs without configuration drift.

### Base Configuration Layer

Every deployment starts with **[`docker-compose.base.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.base.yml)**, which contains the essential service definitions required regardless of hardware target. This file establishes the networking, volumes, and base environment variables upon which GPU-specific modifications are applied.

### GPU Backend Selection

The resolver selects vendor-specific overlays based on the `--gpu-backend` argument or the `GPU_BACKEND` environment variable. According to lines 119-136 of [`resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/resolve-compose-stack.sh), the script implements the following selection logic:

```bash
elif gpu_backend == "amd":
    if existing(["docker-compose.base.yml", "docker-compose.amd.yml"]):
        resolved = ["docker-compose.base.yml", "docker-compose.amd.yml"]
elif gpu_backend in ("intel", "sycl") or tier in ("ARC", "ARC_LITE"):
    if existing(["docker-compose.base.yml", "docker-compose.arc.yml"]):
        resolved = ["docker-compose.base.yml", "docker-compose.arc.yml"]
else:   # default = nvidia

    if existing(["docker-compose.base.yml", "docker-compose.nvidia.yml"]):
        resolved = ["docker-compose.base.yml", "docker-compose.nvidia.yml"]

```

The available backend overlays include:
- **[`docker-compose.nvidia.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.nvidia.yml)** – Default overlay for NVIDIA GPUs (CUDA runtime and device mappings)
- **[`docker-compose.amd.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.amd.yml)** – AMD GPU support via ROCm
- **[`docker-compose.arc.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.arc.yml)** – Intel ARC and SYCL-compatible GPUs
- **[`docker-compose.apple.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.apple.yml)** – Apple Silicon GPU support (alternatively [`installers/macos/docker-compose.macos.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/installers/macos/docker-compose.macos.yml) on macOS)
- **[`docker-compose.cpu.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.cpu.yml)** – CPU-only fallback mode (lines 101-106)

### Multi-GPU Support

For systems with multiple GPUs, the resolver appends **[`docker-compose.multigpu.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.multigpu.yml)** when `--gpu-count` exceeds 1 and the file exists on disk (lines 44-46 of [`resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/resolve-compose-stack.sh)). This overlay adjusts service replicas or resource allocations to distribute workloads across available GPU hardware.

## Extension-Specific GPU Configurations

Individual extensions can supply their own compose files with optional GPU-specific variants. As documented in **[`extensions/CATALOG.md`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/extensions/CATALOG.md)**, extensions may structure their configurations as:

- **[`compose.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose.yaml)** – Base extension services
- **[`compose.nvidia.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose.nvidia.yaml)**, **[`compose.amd.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose.amd.yaml)**, etc. – Backend-specific overrides

The resolver automatically detects and merges these extension overlays alongside the main stack files, ensuring that services requiring GPU access receive the correct device constraints regardless of the underlying hardware.

## Practical Usage Examples

### Resolving for AMD GPUs

```bash
scripts/resolve-compose-stack.sh \
    --script-dir "$PWD" \
    --tier 1 \
    --gpu-backend amd

# Output: -f docker-compose.base.yml -f docker-compose.amd.yml

```

### CPU-Only Deployment

When `gpu_backend` is explicitly set to `cpu`, the resolver bypasses vendor overlays and uses the CPU-specific fallback:

```bash
scripts/resolve-compose-stack.sh \
    --gpu-backend cpu

# Output: -f docker-compose.base.yml -f docker-compose.cpu.yml

```

### Multi-GPU NVIDIA Configuration

```bash
scripts/resolve-compose-stack.sh \
    --gpu-backend nvidia \
    --gpu-count 2

# Output: -f docker-compose.base.yml -f docker-compose.nvidia.yml -f docker-compose.multigpu.yml

```

### Integration with Dream CLI

The Dream CLI internally invokes this resolver before executing Docker Compose commands:

```bash
dream-cli up

# Internally executes:

# COMPOSE_FLAGS=$(scripts/resolve-compose-stack.sh --script-dir "$INSTALL_DIR" \

#                     --tier "$TIER" --gpu-backend "$GPU_BACKEND")

# docker compose $COMPOSE_FLAGS up -d

```

## Key Configuration Files

| File | Role |
|------|------|
| [`scripts/resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/scripts/resolve-compose-stack.sh) | Core resolver script that selects and merges compose files (lines 90-136) |
| [`docker-compose.base.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.base.yml) | Hardware-agnostic base services required for all deployments |
| [`docker-compose.nvidia.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.nvidia.yml) | NVIDIA GPU device mappings and CUDA runtime volumes |
| [`docker-compose.amd.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.amd.yml) | AMD ROCm-specific service overrides |
| [`docker-compose.intel.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.intel.yml) / [`docker-compose.arc.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.arc.yml) | Intel GPU and SYCL support configurations |
| [`docker-compose.apple.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.apple.yml) | Apple Silicon GPU settings |
| [`docker-compose.cpu.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.cpu.yml) | CPU-only mode disabling GPU device requirements |
| [`docker-compose.multigpu.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.multigpu.yml) | Multi-GPU resource scaling and replica configuration |
| `extensions/**/compose.yaml` & `extensions/**/compose.<backend>.yaml` | Per-extension service definitions with optional GPU-specific overlays |

## Summary

- Dream Server uses a **layered overlay approach** to handle GPU-specific configurations in Docker Compose without modifying core service definitions.
- The **[`resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/resolve-compose-stack.sh)** script automatically selects the appropriate backend overlay based on the `--gpu-backend` argument or `GPU_BACKEND` environment variable.
- **Supported backends** include NVIDIA, AMD, Intel/SYCL, Intel ARC, Apple Silicon, and CPU-only modes, each with dedicated compose files.
- **Multi-GPU deployments** append an additional overlay when `--gpu-count` exceeds 1, enabling distributed GPU utilization.
- **Extensions** can provide their own GPU-specific compose overlays that the resolver merges automatically with the main stack.

## Frequently Asked Questions

### How does Dream Server detect which GPU backend to use?

Dream Server relies on explicit configuration through the `--gpu-backend` command-line argument or the `GPU_BACKEND` environment variable. The resolver script in [`scripts/resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/scripts/resolve-compose-stack.sh) evaluates these inputs against supported values (`nvidia`, `amd`, `intel`, `sycl`, `arc`, `apple`, `cpu`) to determine which overlay files to include, defaulting to NVIDIA if no specific backend is specified.

### Can I run Dream Server without a GPU?

Yes. Set `--gpu-backend cpu` when invoking the resolver. This configuration replaces the vendor-specific GPU overlay with [`docker-compose.cpu.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.cpu.yml), which configures services to run on CPU-only resources. The script explicitly handles this fallback case at lines 101-106 of [`resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/resolve-compose-stack.sh).

### What happens if I have multiple GPUs?

When `--gpu-count` is greater than 1, the resolver checks for the existence of [`docker-compose.multigpu.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.multigpu.yml) and appends it to the compose file list (lines 44-46). This overlay typically contains service replicas or resource constraints necessary to distribute workloads across multiple GPU devices simultaneously.

### How do extensions add their own GPU configurations?

Extensions can include a [`compose.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose.yaml) file for base services and optional backend-specific files such as [`compose.nvidia.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose.nvidia.yaml) or [`compose.amd.yaml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/compose.amd.yaml) within their directory. The resolver discovers these files automatically and merges them with the main stack, as documented in [`extensions/CATALOG.md`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/extensions/CATALOG.md), ensuring extensions receive the correct GPU device mappings for the target hardware.