What Is the Purpose of `docker-compose.base.yml` in Dream Server?

docker-compose.base.yml defines the core service stack that powers Dream Server, containing mandatory containers for LLM inference, chat UI, and dashboard services, while serving as the foundation that GPU-specific overlays and extension services are layered upon.

The docker-compose.base.yml file in the Light-Heart-Labs/DreamServer repository is the essential blueprint for every deployment. According to the Dream Server source code, this base configuration establishes the mandatory services, logging policies, and network isolation required to run the platform, while remaining agnostic to specific hardware backends.

Core Services Defined in docker-compose.base.yml

The base file declared in docker-compose.base.yml (lines 24–228) specifies four critical services that form the backbone of any Dream Server instance.

Mandatory Container Stack

• llama-server – Provides the LLM inference API (lines 24–88)
• open-webui – Serves the chat interface for user interactions (lines 70–88)
• dashboard-api – Acts as the system-status backend (lines 100–154)
• dashboard – Hosts the control-center UI for administration (lines 168–228)

Each service includes health-check configurations and dependency mapping that ensure the stack initializes in the correct order.

Shared Infrastructure Components

Beyond application containers, docker-compose.base.yml establishes the common operational layer. The file defines an x-logging: &default-logging anchor (lines 10–16) that enforces centralized JSON-file logging across all containers. It also creates the isolated dream-network bridge network (lines 90–93) to separate Dream Server traffic from the host network, preventing port conflicts and improving security.

How the Base File Enables Modular GPU Support

The architectural purpose of docker-compose.base.yml extends beyond service definition; it functions as the immutable foundation for a layered configuration system.

Hardware-Agnostic Placeholders

The base file intentionally uses placeholder variables such as ${LLAMA_SERVER_IMAGE} rather than hardcoding image tags. This abstraction allows GPU-specific overlay files to inject the correct drivers and resource mappings without modifying core service definitions.

GPU Overlay Composition

Three overlay files extend the base configuration based on detected hardware:

• docker-compose.nvidia.yml – Injects NVIDIA device mappings and CUDA-specific image variants
• docker-compose.amd.yml – Applies ROCm configurations for AMD GPUs
• docker-compose.apple.yml – Configures Apple Silicon support with Metal-specific parameters

The comment header in docker-compose.base.yml (lines 2–5) explicitly documents this extension pattern, establishing that these overlays "supply hardware-specific image tags, device mappings, and resource limits" that override the base placeholders.

Extension Service Discovery

The modular architecture also supports optional add-ons located at extensions/services/*/compose.yaml. Components such as ComfyUI or Whisper provide their own compose.yaml files that merge into the final stack. As noted in the base file comments (line 2), these extensions are discovered and layered at runtime, allowing users to extend functionality without altering the core docker-compose.base.yml.

Automated Stack Resolution

While manual composition is possible, Dream Server provides scripts/resolve-compose-stack.sh to automate the merging process. This script detects the host GPU tier, selects the appropriate overlay, scans the extensions/services directory for additional compose files, and executes Docker Compose with the complete file set.

Manual Stack Deployment

For explicit control, you can combine the base file with overlays manually:

# NVIDIA GPU deployment

docker compose -f docker-compose.base.yml -f docker-compose.nvidia.yml up -d

# AMD GPU deployment

docker compose -f docker-compose.base.yml -f docker-compose.amd.yml up -d

Automated Deployment with Resolver Script

To leverage automatic hardware detection and extension discovery:

# Detect hardware, merge extensions, and start services

./scripts/resolve-compose-stack.sh up -d

The resolver internally constructs a command equivalent to:

docker compose -f docker-compose.base.yml -f docker-compose.${GPU_BACKEND}.yml $(find extensions/services -name compose.yaml) up -d

Configuration Verification

Before deploying, inspect the effective merged configuration:

./scripts/resolve-compose-stack.sh config

This outputs the final Docker Compose configuration after all overlays and extensions have been merged, allowing you to verify resource limits and image tags before container startup.

Stack Teardown

To stop and remove the entire Dream Server stack including extension services:

./scripts/resolve-compose-stack.sh down --remove-orphans

Summary

• docker-compose.base.yml serves as the mandatory foundation for every Dream Server deployment, defining core services (llama-server, open-webui, dashboard-api, dashboard) and shared infrastructure.
• The file uses placeholder variables to remain hardware-agnostic, allowing GPU-specific overlays (docker-compose.nvidia.yml, docker-compose.amd.yml, docker-compose.apple.yml) to inject appropriate drivers and device mappings.
• Extension services under extensions/services/*/compose.yaml merge into the base stack at runtime, enabling modular functionality without modifying core files.
• scripts/resolve-compose-stack.sh automates the composition process, detecting hardware tiers and assembling the final configuration from the base file, selected overlays, and discovered extensions.

Frequently Asked Questions

What happens if I run docker-compose.base.yml without an overlay?

Running only docker-compose.base.yml will fail to deploy functional LLM inference because the ${LLAMA_SERVER_IMAGE} placeholder and GPU device mappings remain undefined. The base file requires at least one GPU overlay (NVIDIA, AMD, or Apple) to resolve hardware-specific configurations and provide valid container images.

Can I modify docker-compose.base.yml directly to add my own services?

While technically possible, directly modifying docker-compose.base.yml is discouraged because it complicates updates and version control. Instead, place custom service definitions in extensions/services/*/compose.yaml files, which the resolve-compose-stack.sh script automatically discovers and merges alongside the base configuration.

How does the resolve-compose-stack.sh script detect which GPU overlay to use?

The script analyzes the host system for GPU hardware characteristics and driver availability, then selects the appropriate overlay file (docker-compose.nvidia.yml, docker-compose.amd.yml, or docker-compose.apple.yml) based on detected capabilities. This automated detection removes the need for manual hardware specification when starting the Dream Server stack.

Are the health checks defined in docker-compose.base.yml sufficient for production use?

The health-check configurations defined in docker-compose.base.yml (referenced across lines 24–228) provide basic service availability monitoring suitable for most deployments. However, production environments may require customizing interval and timeout values or adding additional health-check endpoints within the individual service images to match specific SLA requirements.

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