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

> Discover the purpose of docker-compose.base.yml in Dream Server. This file defines the core service stack for LLM inference, chat UI, and dashboard, serving as the foundation for your Dream Server setup.

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

---

**[`docker-compose.base.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.base.yml) file in the [Light-Heart-Labs/DreamServer](https://github.com/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.nvidia.yml)** – Injects NVIDIA device mappings and CUDA-specific image variants
- **[`docker-compose.amd.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.amd.yml)** – Applies ROCm configurations for AMD GPUs
- **[`docker-compose.apple.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.apple.yml)** – Configures Apple Silicon support with Metal-specific parameters

The comment header in [`docker-compose.base.yml`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/docker-compose.base.yml).

## Automated Stack Resolution

While manual composition is possible, Dream Server provides **[`scripts/resolve-compose-stack.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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:

```bash

# 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:

```bash

# Detect hardware, merge extensions, and start services

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

```

The resolver internally constructs a command equivalent to:

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

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

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

```

## Summary

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