Understanding Top-Level Configs in Docker Compose

--- title: Configs top-level elements description: Explore all the attributes the configs top-level element can have. keywords: compose, compose specification, configs, compose file reference aliases: - /compose/compose-file/08-configs/ weight: 50 --- {{% include "compose/configs.md" %}} Services can only access configs when explicitly granted by a [`configs`](services.md#configs) attribute within the `services` top-level element. By default, the config: - Is owned by the user running the container command but can be overridden by service configuration. - Has world-readable permissions (mode 0444), unless the service is configured to override this. The top-level `configs` declaration defines or references configuration data that is granted to services in your Compose application. The source of the config is either `file` or `external`. - `file`: The config is created with the contents of the file at the specified path. - `environment`: The config content is created with the value of an environment variable. Introduced in Docker Compose version [2.23.1](/manuals/compose/releases/release-notes.md#2231). - `content`: The content is created with the inlined value. Introduced in Docker Compose version [2.23.1](/manuals/compose/releases/release-notes.md#2231). - `external`: If set to true, `external` specifies that this config has already been created. Compose does not attempt to create it, and if it does not exist, an error occurs. - `name`: The name of the config object in the container engine to look up. This field can be used to reference configs that contain special characters. The name is used as is and will **not** be scoped with the project name. ## Example 1 `<project_name>_http_config` is created when the application is deployed, by registering the content of the `httpd.conf` as the configuration data. ```yml configs: http_config: file: ./httpd.conf ``` Alternatively, `http_config` can be declared as external. Compose looks up `http_config` to expose the configuration data to relevant services. ```yml configs: http_config: external: true ``` ## Example 2 `<project_name>_app_config` is created when the application is deployed, by registering the inlined content as the configuration data. This means Compose infers variables when creating the config, which allows you to adjust content according to service configuration: ```yml configs: app_config: content: | debug=${DEBUG} spring.application.admin.enabled=${DEBUG} spring.application.name=${COMPOSE_PROJECT_NAME} ``` ## Example 3 External configs lookup can also use a distinct key by specifying a `name`. The following example modifies the previous one to look up a config using the parameter `HTTP_CONFIG_KEY`. The actual lookup key is set at deployment time by the [interpolation](interpolation.md) of variables, but exposed to containers as hard-coded ID `http_config`. ```yml configs: http_config: external: true name: "${HTTP_CONFIG_KEY}" ``` If `external` is set to `true`, all other attributes apart from `name` are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid.

This document explains the `configs` top-level element in Docker Compose, which defines or references configuration data accessible to services. Configs can be sourced from files, environment variables, inlined content, or declared as external. When declaring a config, you can specify a file, environment, or content as the source, or indicate that the config is external and already exists. Additionally, a `name` can be specified for external configs to look up the config object in the container engine. The examples illustrate how to define configs using files, inlined content, and external references, demonstrating the flexibility in managing configuration data within a Compose application.