9.2.4 Compose Configs

Compose configs provide a mechanism for managing configuration data separately from a service's image, defined under a Compose file's top-level configs key and mounted into whichever services need that particular configuration, distinct from environment variables or general-purpose volume mounts.

Declaring and Using a Config

A config is declared at the top level, referencing either a local file or inline content, and then attached to whichever services need it.

services:
  api:
    configs:
      - source: api-config
        target: /app/config.yaml

configs:
  api-config:
    file: ./config/api-config.yaml

This makes the content of ./config/api-config.yaml available inside the api service's container at /app/config.yaml.

Why Configs Differ From a Simple Bind Mount

While functionally similar to a read-only bind mount for many local development purposes, the configs mechanism is part of a broader concept originally designed for Swarm's distributed configuration management, where configuration content is distributed to whichever nodes in a cluster actually need it, rather than depending on every node already having an equivalent local file.

configs:
  api-config:
    file: ./config/api-config.yaml

Defining Inline Config Content

Rather than always referencing an external file, a config's content can be specified directly within the Compose file itself.

configs:
  api-config:
    content: |
      log_level: debug
      port: 8080

Why Configs Are Generally Treated as Non-Sensitive

Unlike secrets, configs are intended for non-sensitive configuration data — anything genuinely sensitive should instead use Compose's dedicated secrets mechanism, which handles that kind of data with additional precautions configs don't provide.

configs:
  api-config:
    file: ./config/non-sensitive-settings.yaml

Why Compose Configs Matter

The configs mechanism provides a structured way to manage and distribute non-sensitive configuration data to services that need it, particularly valuable in clustered deployment contexts where simple bind mounts referencing local host paths aren't a reliable option.