Compose file version 1 reference

Estimated reading time:
14 minutes

Reference and guidelines

These topics describe version 1 of the Compose file format. This is the oldest
version.

Compose and Docker compatibility matrix

There are several versions of the Compose file format – 1, 2, 2.x, and 3.x The
table below is a quick look. For full details on what each version includes and
how to upgrade, see About versions and upgrading.

In addition to Compose file format versions shown in the table, the Compose
itself is on a release schedule, as shown in Compose
releases, but file format versions
do not necessarily increment with each release. For example, Compose file format
3.0 was first introduced in Compose release
1.10.0, and versioned
gradually in subsequent releases.

Note: Setting entrypoint both overrides any default entrypoint set
on the service’s image with the ENTRYPOINT Dockerfile instruction, and
clears out any default command on the image - meaning that if there’s a CMD
instruction in the Dockerfile, it is ignored.

env_file

Add environment variables from a file. Can be a single value or a list.

If you have specified a Compose file with docker-compose -f FILE, paths in
env_file are relative to the directory that file is in.

Compose expects each line in an env file to be in VAR=VAL format. Lines
beginning with # are processed as comments and are ignored. Blank lines are
also ignored.

# Set Rails/Rack environment
RACK_ENV=development

Note: If your service specifies a build option, variables
defined in environment files are not automatically visible during the
build.

The value of VAL is used as is and not modified at all. For example if the
value is surrounded by quotes (as is often the case of shell variables), the
quotes are included in the value passed to Compose.

Keep in mind that the order of files in the list is significant in determining
the value assigned to a variable that shows up more than once. The files in the
list are processed from the top down. For the same variable specified in file
a.env and assigned a different value in file b.env, if b.env is
listed below (after), then the value from b.env stands. For example, given the
following declaration in docker_compose.yml:

services:some-service:env_file:-a.env-b.env

And the following files:

# a.env
VAR=1

and

# b.env
VAR=hello

$VAR is hello.

environment

Add environment variables. You can use either an array or a dictionary. Any
boolean values; true, false, yes no, need to be enclosed in quotes to ensure
they are not converted to True or False by the YML parser.

Environment variables with only a key are resolved to their values on the
machine Compose is running on, which can be helpful for secret or host-specific values.

Note: If your service specifies a build option, variables
defined in environment are not automatically visible during the
build.

expose

Expose ports without publishing them to the host machine - they’ll only be
accessible to linked services. Only the internal port can be specified.

expose:
- "3000"
- "8000"

extends

Extend another service, in the current file or another, optionally overriding
configuration.

You can use extends on any service together with other configuration keys.
The extends value must be a dictionary defined with a required service
and an optional file key.

extends:
file: common.yml
service: webapp

The service the name of the service being extended, for example
web or database. The file is the location of a Compose configuration
file defining that service.

If you omit the file Compose looks for the service configuration in the
current file. The file value can be an absolute or relative path. If you
specify a relative path, Compose treats it as relative to the location of the
current file.

You can extend a service that itself extends another. You can extend
indefinitely. Compose does not support circular references and docker-compose
returns an error if it encounters one.

external_links

Link to containers started outside this docker-compose.yml or even outside
of Compose, especially for containers that provide shared or common services.
external_links follow semantics similar to links when specifying both the
container name and the link alias (CONTAINER:ALIAS).

pid

pid: "host"

Sets the PID mode to the host PID mode. This turns on sharing between
container and the host operating system the PID address space. Containers
launched with this flag can access and manipulate other
containers in the bare-metal machine’s namespace and vise-versa.

ports

Expose ports. Either specify both ports (HOST:CONTAINER), or just the container
port (an ephemeral host port is chosen).

Note: When mapping ports in the HOST:CONTAINER format, you may experience
erroneous results when using a container port lower than 60, because YAML
parses numbers in the format xx:yy as a base-60 value. For this reason,
we recommend always explicitly specifying your port mappings as strings.

security_opt

stop_signal

Sets an alternative signal to stop the container. By default stop uses
SIGTERM. Setting an alternative signal using stop_signal causes
stop to send that signal instead.

stop_signal: SIGUSR1

ulimits

Override the default ulimits for a container. You can either specify a single
limit as an integer or soft/hard limits as a mapping.

ulimits:
nproc: 65535
nofile:
soft: 20000
hard: 40000

volumes, volume_driver

Mount paths or named volumes, optionally specifying a path on the host machine
(HOST:CONTAINER), or an access mode (HOST:CONTAINER:ro).
For version 2 files, named volumes need to be specified with the
top-level volumes key.
When using version 1, the Docker Engine creates the named
volume automatically if it doesn’t exist.

You can mount a relative path on the host, which expands relative to
the directory of the Compose configuration file being used. Relative paths
should always begin with . or ...

For version 1 files, both named volumes and
container volumes use the specified driver.

No path expansion is done if you have also specified a volume_driver.
For example, if you specify a mapping of ./foo:/data, the ./foo part
is passed straight to the volume driver without being expanded.