9.2.4.2 Compose File Configs

Compose file configs are the local files referenced by a declared config's file option, providing the actual source content that gets injected into whichever services reference that config, keeping configuration content organized as ordinary, version-controllable files alongside the Compose file itself.

Referencing a Local File as a Config Source

The file option points to a specific local file whose content becomes the config's injected content.

configs:
  nginx-config:
    file: ./nginx/nginx.conf

services:
  web:
    image: nginx:alpine
    configs:
      - source: nginx-config
        target: /etc/nginx/nginx.conf

Why Keeping Configuration in Separate Files Aids Organization

Maintaining configuration content in its own dedicated file, rather than inlined directly within the Compose file, keeps both more focused and readable, particularly as configuration content grows more substantial.

nginx/
  nginx.conf
docker-compose.yml

This separation also allows the configuration file to be edited, reviewed, and version-controlled using whatever tools are appropriate for its specific format, independent of the Compose file's own YAML structure.

Updating a File-Based Config

Changing the referenced file's content and recreating the affected service picks up the updated configuration.

docker compose up -d --force-recreate web

Compose doesn't automatically detect and apply a changed config file to an already-running container — an explicit recreation is needed for the update to take effect.

Using Multiple File-Based Configs Together

Several distinct configuration files can each be declared as their own config, injected into the same or different services as needed.

configs:
  nginx-main:
    file: ./nginx/nginx.conf
  nginx-sites:
    file: ./nginx/sites-enabled.conf

Why Compose File Configs Matter

Referencing configuration content through ordinary, separately maintained files keeps a Compose application's configuration well organized and properly version-controlled, while still allowing that content to be reliably and consistently injected into the services that need it.