How Dream Server Manages GPU-Specific Configurations in Docker Compose

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 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, 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, 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, the script implements the following selection logic:

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 – Default overlay for NVIDIA GPUs (CUDA runtime and device mappings)
• docker-compose.amd.yml – AMD GPU support via ROCm
• docker-compose.arc.yml – Intel ARC and SYCL-compatible GPUs
• docker-compose.apple.yml – Apple Silicon GPU support (alternatively installers/macos/docker-compose.macos.yml on macOS)
• 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 when --gpu-count exceeds 1 and the file exists on disk (lines 44-46 of 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, extensions may structure their configurations as:

• compose.yaml – Base extension services
• compose.nvidia.yaml, 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

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:

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

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

Multi-GPU NVIDIA Configuration

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:

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	Core resolver script that selects and merges compose files (lines 90-136)
docker-compose.base.yml	Hardware-agnostic base services required for all deployments
docker-compose.nvidia.yml	NVIDIA GPU device mappings and CUDA runtime volumes
docker-compose.amd.yml	AMD ROCm-specific service overrides
docker-compose.intel.yml / docker-compose.arc.yml	Intel GPU and SYCL support configurations
docker-compose.apple.yml	Apple Silicon GPU settings
docker-compose.cpu.yml	CPU-only mode disabling GPU device requirements
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 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 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, 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.

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 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 file for base services and optional backend-specific files such as compose.nvidia.yaml or 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, ensuring extensions receive the correct GPU device mappings for the target hardware.

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