The Compose file
The Compose file is a YAML file defining
version (DEPRECATED),
services (REQUIRED),
networks,
volumes,
configs and
secrets.
The default path for a Compose file is compose.yaml
(preferred) or compose.yml
in working directory.
Compose implementations SHOULD also support docker-compose.yaml
and docker-compose.yml
for backward compatibility.
If both files exist, Compose implementations MUST prefer canonical compose.yaml
one.
Multiple Compose files can be combined together to define the application model. The combination of YAML files MUST be implemented by appending/overriding YAML elements based on Compose file order set by the user. Simple attributes and maps get overridden by the highest order Compose file, lists get merged by appending. Relative paths MUST be resolved based on the first Compose file’s parent folder, whenever complimentary files being merged are hosted in other folders.
As some Compose file elements can both be expressed as single strings or complex objects, merges MUST apply to the expanded form.
Profiles
Profiles allow to adjust the Compose application model for various usages and environments. A Compose implementation SHOULD allow the user to define a set of active profiles. The exact mechanism is implementation specific and MAY include command line flags, environment variables, etc.
The Services top-level element supports a profiles
attribute to define a list of named profiles. Services without
a profiles
attribute set MUST always be enabled. A service MUST be ignored by the Compose
implementation when none of the listed profiles
match the active ones, unless the service is
explicitly targeted by a command. In that case its profiles
MUST be added to the set of active profiles.
All other top-level elements are not affected by profiles
and are always active.
References to other services (by links
, extends
or shared resource syntax service:xxx
) MUST not
automatically enable a component that would otherwise have been ignored by active profiles. Instead the
Compose implementation MUST return an error.
Illustrative example
services:
foo:
image: foo
bar:
image: bar
profiles:
- test
baz:
image: baz
depends_on:
- bar
profiles:
- test
zot:
image: zot
depends_on:
- bar
profiles:
- debug
- Compose application model parsed with no profile enabled only contains the
foo
service. - If profile
test
is enabled, model contains the servicesbar
andbaz
, which are enabled by thetest
profile, and servicefoo
, which is always enabled. - If profile
debug
is enabled, model contains bothfoo
andzot
services, but notbar
andbaz
, and as such the model is invalid regarding thedepends_on
constraint ofzot
. - If profiles
debug
andtest
are enabled, model contains all services:foo
,bar
,baz
andzot
. - If Compose implementation is executed with
bar
as explicit service to run, it and thetest
profile will be active even iftest
profile is not enabled by the user. - If Compose implementation is executed with
baz
as explicit service to run, the servicebaz
and the profiletest
will be active andbar
will be pulled in by thedepends_on
constraint. - If Compose implementation is executed with
zot
as explicit service to run, again the model will be invalid regarding thedepends_on
constraint ofzot
, sincezot
andbar
have no commonprofiles
listed. - If Compose implementation is executed with
zot
as explicit service to run and profiletest
enabled, profiledebug
is automatically enabled and servicebar
is pulled in as a dependency starting both serviceszot
andbar
.