Config Reference

Overview of all configuration files in the DWE system.

New to DWE? Start with Getting started for an end-to-end walkthrough, then return here for the file-by-file reference.

File inventory
Loader topology
Merged vs standalone
Pages
Related commands

File inventory

File	Tracked	Loader	Purpose
`workspace.yml`	yes	layer 1	Project identity and service structure
`workspace/defaults.yml`	yes	layer 2	Versioned defaults: runtime, exports, service enabled toggles
`workspace/local.yml`	no (gitignored)	layer 3	Per-user overrides: state, service enabled toggles
`workspace/services/<name>/service.yml`	yes	standalone	Per-service declaration (dirs, cli, configs, ports)
`workspace/deploy.yml`	yes	standalone	Orchestrator deploy pipeline (phases + steps)
`workspace/services/<name>/deploy.yml`	yes	standalone	Per-service deploy pipelines
`workspace/reset.yml`	yes	standalone	Reset pipeline
`workspace/lifecycle.yml`	yes	standalone	Run / stop pipelines (driving `dwe run`/`stop`/`restart`)
`workspace/docker.yml`	yes	standalone	Compose execution policy
`workspace/docker.local.yml`	no (gitignored)	merged into `docker.yml`	Local compose policy overrides
`workspace/styles.yml`	yes	standalone	ASCII header, color palette, separator
`workspace/info.yml`	yes	standalone	Info dashboard sections
`workspace/commands/`	yes	standalone	Declarative command definitions (per-file groups)
`workspace/validate.yml`	yes	standalone	Project readiness checks (preflight + `dwe validate`)
`workspace/snapshot.yml`	yes	standalone	Snapshot workflows: create / restore / remove (`dwe snapshot`)
`workspace/tests/<scenario>.yml`	yes	standalone	Integration-test scenarios: isolated deploy + assertion steps (`dwe test`)
`workspace/i18n/*.yml`	yes	standalone	User command and UI string translations (optional; one file per language)

Runtime artifacts

The .dwe/ directory contains DWE-managed artifacts and is gitignored:

.dwe/logs/ — pipeline logs (deploy, reset, lifecycle run/stop)
.dwe/deploy/deploy.lock — deployment lock file (Unix-only; prevents parallel deploys)
.dwe/deploy/state.yml — deployment state journal (tracks service deploy status and hashes)
.dwe/snapshots/snapshot.lock — snapshot lock file (Unix-only; serialises snapshot mutating commands and is co-acquired by deploy lifecycle commands)
.dwe/snapshots/current — current snapshot pointer (last created or restored snapshot)
.dwe/snapshots/.pre-restore-backup/ — backup of workspace/local.yml + .dwe/deploy/state.yml taken before each restore; manual recovery target on restore failure
.dwe/tests/runs/<scenario>/, .dwe/tests/locks/<scenario>.lock, .dwe/tests/manifests/<scenario>-<run-id>.yml, .dwe/tests/reports/<scenario>/ — dwe test scenario copies, per-scenario flocks, durable run manifests, and failure-report artifacts (collected only on failure)

Add .dwe/ to your project’s .gitignore if not already present.

Loader topology

flowchart LR
  subgraph merged["3-layer merge — DweConfig"]
    direction TB
    A[workspace.yml] --> B[workspace/defaults.yml] --> C[workspace/local.yml]
  end

  S["workspace/services/&lt;name&gt;/service.yml"] -. injected into Raw .-> merged

  merged --> R[(DweConfig.Raw<br/>+ typed structs)]

  subgraph standalone["Standalone loaders"]
    direction TB
    D[workspace/deploy.yml]
    DS["workspace/services/&lt;name&gt;/deploy.yml"]
    RS[workspace/reset.yml]
    L[workspace/lifecycle.yml]
    DK[workspace/docker.yml<br/>+ docker.local.yml]
    ST[workspace/styles.yml]
    IN[workspace/info.yml]
    CM[workspace/commands/]
  end

  R -. "dot-paths / templates" .-> D
  R -. "dot-paths / templates" .-> DS
  R -. "dot-paths / templates" .-> RS
  R -. "dot-paths / templates" .-> L
  R -. "$#123;...#125; project_name" .-> DK
  R -. "#123;#123;...#125;#125; expressions" .-> IN
  R -. "$#123;...#125; command params" .-> CM

Merged vs standalone

Merged (3-layer config): workspace.yml → workspace/defaults.yml → workspace/local.yml are deep-merged at startup. Later layers win; maps merge recursively. The result is the effective config used for .env generation, topology resolution, and export rules. Each workspace/services/<name>/service.yml is loaded separately and then injected into the merged raw map so dot-paths like services.main.container resolve.

Standalone: workspace/services/<name>/service.yml, deploy.yml, workspace/services/<name>/deploy.yml, reset.yml, lifecycle.yml, docker.yml (+ docker.local.yml), styles.yml, info.yml, and commands/*.yml are loaded by dedicated functions in internal/core/project/config/ and internal/core/usercommands/. They are not part of the 3-layer merge but most of them resolve template expressions against the merged config.

Files that support local overrides

Currently, only docker.local.yml supports a .local.yml variant for per-developer customization. The pattern is:

Docker: workspace/docker.yml (tracked, shared project-wide) + workspace/docker.local.yml (gitignored, per-developer). The local file is merged on top of the base file, allowing developers to customize their compose execution policy — e.g., add extra volumes, mount local source directories, or override platform/args without affecting teammates.

Why only docker? Docker setups are inherently personal — they depend on the developer’s local environment (available binaries, volume mounts, platform differences). Other configs like lifecycle.yml, info.yml, and styles.yml are shared project-wide and don’t benefit from per-developer overrides.

For more details on docker.local.yml semantics and examples, see docker.yml.

Config Reference

Contents

File inventory

Runtime artifacts

Loader topology

Merged vs standalone

Files that support local overrides

Pages

Related commands