月份：2017年1月

配置项可以包含环境变量。compose使用docker-compose运行所在的shell环境的变量值。例如，假设shell包含环境变量EXTERNAL_PORT=8000且配置中引用了此变量：

当使用此配置插docker-compose run命令时，compose在shell中查找EXTERNAL_PORT环境变量并使用其值替换此配置文件中对应的占位符。在这个示例中，在创建web容器之前，compose解析端口映射为8000:5000。

如果环境变量没有设置，compose使用空字符替换。在上面的示例中，如果EXTERNAL_PORT没有设置，端口映射的值为:5000(是一个无效的端口映射，创建容器时会导致错误)。

可以使用.env文件为环境变量设置默认的值。在shell环境中设置的值会覆盖在.env文件设置的值。

$VARIABLE和${VARIABLE}两种写法都支持。如果使用的是2.1文件格式，还可以在一行中设置默认的值：

${VARIABLE:-default}：当VARIABLE没有设置或为空值时使用default值。

${VARIABLE-default} ：仅当VARIABLE没有设置时使用default值。

其它的shell风格的扩展功能，如${VARIABLE/foo/bar}不支持。

可以使用双美元符号来转义美元符号，即阻止compose解析为值。

driver

指定用于这个网络的驱动。

默认使用的驱动取决于docker engine的配置，但大多数情况中，单台主机中使用的是bridge，在集群中使用的是overlay。

driver_opts

指定一列键值对选项传递给这个数据卷的驱动。这些选项依赖于驱动。此参数可选。

enable_ipv6

在这个网络启用IPv6网络支持。从version 2.1文件格式可用。

ipam

指定自定义IPAM配置。这个是带几个属性的对象，每个属性都是可选的：

driver: 自定义IPAM驱动，而不是default。

config: 0个或多个配置块，可以是以下键：
subnet：表示一个网段的CIDR格式的子网
ip_range：从指定范围分配容器IP
gateway：主子网的IPv4或IPv6网关
aux_addresses：网络驱动程序使用的辅助IPv4或IPv6地址，作为从主机名到IP的映射

一个完整的示例：

driver

指定这个数据卷使用的数据卷驱动。默认为local。如果驱动不可用，docker engine将会返回一个错误。

driver_opts

指定一列键值对选项传递给这个数据卷的驱动。这些选项依赖于驱动。此参数可选。

external

如果设置为true，表示这个数据卷已经在compose外部创建好了。docker-compose up将不会尝试创建它。

external不能与其它的数据卷配置关键词(driver, driver_opts)一起使用。

在下面的示例中，compose不会尝试创建名为[projectname]_data的数据卷，而是仅仅查找一个称为data存在的数据卷并挂载它到db服务的容器。

也可以指定在compose文件内引用的数据卷名称：

build

这个配置选项应用在构建镜像时。

build可以指定包含构建上下文路径的字符串，或者是context指定一个路径和可选的dockerfile和args。

如果指定了image和build，那么compose以image中指定的名称命名构建的镜像，如：

compose将由./dir构建的镜像命名为webapp，tag为tag。

注意：在version 1文件格式中，build有两点不同的地方：
1.只允许build: .一种格式，不允许对象格式。
2.不允许build与image一起使用。

context

context可用于verion 2文件格式或以上版本，version 1中只用build。

指定一个包含Dockerfile的目录路径，或git存储库url。

当指定了一个相对路径，就解析为相对compose文件所在的目录。这个目录也是发送到docker daemon的构建上下文。

dockerfile

替代的Dockerfile

compose使用另一个dockerfile文件构建镜像。必须指定一个context构建路径。

注意：在verions 1文件格式中，dockerfile有两点不同：
1.它出现在build的同级，而不是作为它的子选项：

1. build: .
2. dockerfile: Dockerfile-alternate

2.不允许dockerfile与image一起使用。

args

此选项只支持version 2文件格式和之上版本。

增加build参数，这些参数是只在构建期间访问的环境变量。

首先，在Dockerfile中指定参数：

然后在build下面指定参数。可以传递映射或列表：

compose文件中可以只指定参数名不设置值，在这种情况下参数的值就是compose运行所在shell的环境变量值。

注意：YAML布尔值（true，false，yes，no，on，off）必须用引号引起来，以便解析器将其解释为字符串。

command

覆盖默认的命令。

命令也可以是一个列表，与dockerfile中的列表类似：

container_name

指定一个自定义的容器名称，而不是一个生成的默认名称。

因为docker容器名称必须是唯一的，所以如果指定了一个自定义的名称，不能扩展一个服务超过1个容器。

depends_on

指定服务之间的依赖关系，有两种效果：

docker-compose up将以依赖顺序启动服务。在下面的示例中，db和redis在web之前启动。

docker-compose up SERVICE将自动包括SERVICE的依赖。在下面的示例中，docker-compose up web也会创建和启动db和redis。

简单的示例：

注意：depends_on不会等到db和redis状态为“ready”才启动web – 它只等到它们已经开始启动。如果需要等到一个服务变为ready，查看Controlling startup order

dns

自定义DNS服务器。可以是单个值或列表。

dns_search

自定义search域名。可以是单个值或列表。

tmpfs

需要version 2文件格式或以上版本。

在容器内部挂载一个临时文件系统。可以是单个值或列表。

tmpfs: /run
tmpfs:
– /run
– /tmp

entrypoint

覆盖默认的entrypoint。

entrypoint也可以是一个列表：

注意：设置entrypoint将会覆盖默认使用ENTRYPOINT Dockerfile指令设置服务镜像的entrypoint，也会清除这个镜像的任何默认命令 – 意味着如果Dockerfile中指定的任何CMD指定将会忽略。

env_file

从一个文件添加环境变量。可以是单个值或列表。

如果使用docker-compose -f FILE指定了一个compose文件，那么在env_file的路径就是相对于那个文件所在的目录。

在environment关键词指定的环境变量将会覆盖env_file设置的值。

env文件中每行的格式为VAR=VAL。以#开头的行将忽略，也包括空行。

注意：如果服务指定了一个build选项，定义在env文件中的变量在构建期间不可用。使用build的子选项来定义在构建期间使用的环境变量。

VAL的值按原样使用，不再不修改。 例如，如果值由引号括起来（通常是shell变量的情况），引号将包含在传递给Compose的值中。

environment

添加环境变量。可以使用数组或字典。任何的布尔值,true,false,yes,no需要用引号括起来，以确保YML解析器把它们转换为True或False。

expose

暴露只在链接服务之间可用的端口。只能指定内部使用的端口。

extends

在当前文件或另一个文件扩展另一个服务，可选地覆盖配置。

extends可以与service相关的配置项一起使用。extends的值必须是一个字典，其中service是必须的以及一个可选的file选项。

service指定的是扩展服务到当前服务的名称。例如web或databases。file指定的是定义有那个service的compose文件。

如果不指定file选项，compose则在当前文件查找service的配置。file值可以是一个绝对的或相对的路径。如果指定一个相对的路径，这个路径就是相对于当前文件所在目录的路径。

可以扩展一个本身扩展有另一个的服务。

external_links

链接那些在docker-compose.yml外部启动的容器或甚至是在compose外部的，特别是那么提供共享或通用服务的容器。

external_links在指定容器名称和链接别名（CONTAINER：ALIAS）时遵循类似于链接的语义。

注意：如果使用的是version 2文件格式的compose文件，外部创建的容器必须是连接到与链接到它们的服务同处至少一个相同的网络。

extra_hosts

添加主机名映射。与docker客户端的–add-host参数作用一样。

这些定义的ip地址和主机条目将在容器内部的/etc/hosts文件里，如：

image

指定从其启动容器的镜像。可以是repository/tag或部分镜像ID。

如果镜像不存在，compose尝试拉取它，除非也指定了build，在这种情况下它使用指定的选项来构建镜像并使用指定的tag来作标记。

注意：在version 1文件格式中，不允许build和image一起使用。

links

链接到另一个服务的容器。可以指定服务名称和链接别名(SERVICE:ALIAS),或只是服务名称。

可以使用与别名一样的主机名访问链接服务的容器，或者如果没有指定别名就使用服务名称。

链接也以与depends_on相同的方式表示服务之间的依赖关系，因此它们可以决定服务启动的顺序。

注意：如果定义了links和网络，为了能够通信，链接的服务之间必须至少在一个相同的网络。

logging

version 2文件格式或更高版本。在version 1中，使用是的log_driver和log_opt。

服务的日志配置。

logging:
driver: syslog
options:
syslog-address: “tcp://192.168.0.42:123”

driver名称指定一个服务容器的日志驱动，相当于docker run的–log-driver。
默认的值是json-file。

使用options关键词指定日志驱动的日志选项，就像docker run的log-opt选项。

日志选项是键值对。一个syslog选项的示例：

network_mode

要求version 2文件格式和之后版本。version 1使用net。

网络模式。与docker客户端的–net参数一样，加上一个特别的格式service:[service name]。

networks

要求version 2文件格式和之后版本。version 1使用net。

要加入的网络，在顶层networks关键词之下引用网络。

aliases

在网络中服务的别名(替代主机名)。在同一网络的其它容器可以使用服务名称或这个别名来连接服务容器的其中一个。

因为别名作用域是网络内，所以同一服务在不同的网络可以有不同的别名。

注意：网络范围的别名可以由多个容器共享，甚至是由多个服务。如果是这样，那么该名称解析到哪个容器将不能保证。

一般的格式如下：

在下面的示例中，配置了三个服务(web,worker和db)和两个网络(new和legay)。在net网络上可以使用db主机名或database访问db服务，在legacy网络上可以使用db或mysql访问db服务。

ipv4_address, ipv6_address

加入网络时可以为服务的容器指定静态的IP地址。

顶层networks区域的相关网络配置必须有一个指定有子网和网关覆盖每个静态地址的配置的ipadm块。如果要使用IPv6地址，必须设置com.docker.network.enable_ipv6驱动选项为true。
示例：

ports

暴露端口。可以指定两个端口(HOST:CONTAINER),或只指定一个容器端口(将选择一个随机的主机端口)。

ulimits

覆盖容器默认的ulimits。可以指定单个限制或soft/hard限制。

volumes, volume_driver

挂载路径或命名数据卷，可选地指定主机的路径(HOST:CONTAINER)，或权限模式(HOST:CONTAINER:ro)。对于version 2文件，命名数据卷必须在顶层volumes关键词中指定。当使用version 1时，当命名数据卷不存在时docker engine将会自动创建。

可以挂载主机的一个相对路径，此路径相对于正在使用的compose文件所在的目录。相对的路径以.或..开头。

如果不使用主机路径，可能要指定一个volume_driver。

注意，对于version 2文件，这个驱动不会应用到命名数据卷(当声明数据卷时应该使用driver选项)。对于version 1，命名数据卷和容器数据卷使用这个指定的驱动。

volumes_from

挂载从另一个服务或容器的所有数据卷，可选地指定只读权限(ro)或读写(rw)。如果没有指定权限级别，将使用读写(rw)权限。

cpu_shares, cpu_quota, cpuset, domainname, hostname, ipc, mac_address, mem_limit, memswap_limit, oom_score_adj, privileged, read_only, restart, shm_size, stdin_open, tty, user, working_dir

当在compose定义你的app用于开发环境时，也可以使用这个配置来在不同的环境，如CI,临时和生产环境运行应用程序。

更改compose文件适用于生产环境

在把compose部署到生产环境之前，虽然更改你的app配置，这些更改包括：

删除应用程序代码的挂载，以使代码留在容器内，保证无法从外部更改。

绑定不同的主机端口

设置不同的环境变量(如降低日志的详细程序或启用邮件发送)

指定一个重启策略(如restart: always)来避免宕机时间

增加额外的服务(如，日志聚合器)

以上这么多的更改，可以定义一个额外的compose文件，称为production.yml，定义了适合生产环境的配置。这个文件只需要包含你想要对原始文件的更改部分。可以通过原始docker-compose.yml应用额外的Compose文件来创建新配置。

一旦完成了第二个配置文件的编写，使用-f选项告诉compose使用它：

部署更改

当对你的app代码更改后，需要重建镜像和容器。要重新部署web服务，使用：

第一个命令重建web的镜像然后停止，销毁和重建web服务。–no-deps选项阻止compose重新创建web信赖的服务。

注意：本文涉及的compose只适用于compose文件格式为version 2的版本。verion 1(旧的)不支持网络功能。

默认下compose为你的app配置一个单独的网络。服务中的每个容器都加入到这个默认的网络且在这个网络的容器都能互相通信，它们也能通过与容器名称相同的主机名发现对方。

注意：app的网络基于“项目名称”设置网络名称，这个项目名称基于项目所处的目录名称。可以使用–project-name选项或COMPOSE_PROJECT_NAME环境变量来覆盖它。

例如，假设app在一个名为myapp的目录，docker-compose.yml类似如下：

当执行docker-compose up时，网络部分设置如下：
1.创建了称为myapp_default的网络。
2.使用web的配置创建了容器，然后这个容器加入到myapp_default网络。
3.使用db的配置创建容器，这个容器加入到myapp_default网络。

每个容器现在能查找web或db来得到容器的IP地址。例如，web应用程序的代码可以连接URL postgres://db:5432并开始使用postgres数据库。

由于web明确地映射了一个端口，外部网络也就能通过在docker主机的网络接口的8000端口连接容器。

更新容器

如果更改了服务的配置并执行docker-compose up来更新它，将删除旧的容器并且新的容器加入到相同的网络，分配到了不同的IP地址不过主机名不变。运行中的容器应该能够查找主机名并连接到新的地址，不过旧的地址将失效。

如果任何一个容器与旧的容器有连接，它们会被关闭掉。容器有责任检测这种情况然后重新查找旧容器的主机来重新连接。

链接

链接可以为一个容器定义额外的别名。它们不需要启用服务进行通信 – 默认情况下，任何服务都可以通过该服务的名称访问任何其他服务。在下面的示例中，在web容器中可以通过db和database访问db容器。

指定自定义网络

除了使用默认的app网络之外，还可以使用最顶层networks关键词指定自己定义的网络。这让你可以创建更复制的网络拓扑并指定自定义网络驱动及其选项。也可以使用它来连接服务到不由compose管理的外部创建的网络。

每个服务都能指定连接由networks关键词配置的网络。

下面的示例compose文件定义了两个自定义网络。proxy服务与db服务隔离，因为它们没有指定相同的网络。

也可以通过设置ipv4_address和/或ipv6_address为每个附着的网络配置静态的IP地址。

compose支持两种共享通用配置的方法：
1.通过使用多个compose文件扩展整个compose文件
2.使用extends字段扩展单个服务

多个compose文件

使用多个compose文件可以为不同的环境或不同的工作流自定义compose应用程序。

理解多compose文件

默认下，compose读取两个文件，一个docker-compose.yml和一个可选的docker-compose.override.yml文件。通常来说，docker-compose.yml包含基本的配置。而override文件包含覆盖已存在服务或整个新服务的配置。

如果一个服务在两个文件中都有定义，那么compose就使用在”添加和覆盖配置”中描述的规则合并配置。

要使用多个override文件或不同名称的override文件，可以使用-f选项指定文件列表。compose根据在命令行指定的顺序来合并它们。

当使用多个配置文件时，必须确保文件中所有的路径是相对于base compose文件的(-f指定的第一个compose文件)。这样要求是因此override文件不需要是一个有效的compose文件。override文件可以只包含配置中的小片段。跟踪一个服务的片段是相对于哪个路径的是很困难的且令人困惑的，所以要保持路径容易理解，所以的路径必须定义为相对于base文件的路径。

示例

在本段介绍两个常见的多compose文件用例：为不同的环境更改compose app和针对compose app运行管理任务。

不同的环境

使用多文件的一个常见用例是更改用于类生产环境(可能是生产环境，临时环境或配置项)的开发compose app。要支持这样的更改，可以把一个compose配置文件分割为多个不同的文件：

从定义服务的规范配置的基本文件开始。

docker-compose.yml

在下面这个示例中开发配置暴露了一些端口到主机上，挂载代码目录到容器然后构建web镜像。

docker-compose.override.yml

当执行docker-compose up命令时它会自动读取这个override文件。

现在我们创建另一个用于生产环境的override文件。

docker-compose.prod.yml

要使用这个生产compose文件部署，运行如下命令：

这个将会使用docker-compose.yml和docker-compose.prod.yml(没有用到docker-compose.override.yml)来部署这三个服务。

管理任务

另一个常见的用例是针对在compose app中的一个或多个服务运行adhoc或管理任务。这个示例演示备份运行中的数据库。

docker-compose.yml

在docker-compose.admin.yml中添加一个新服务用到导出数据库或备份。

要启动一个正常的环境运行docker-compose up -d。要备份数据库，运行：

扩展服务

docker compose的extends关键词能够在不同的文件或甚至完全不同的项目之间共享通用的配置。如果有几个重用通用配置项集的服务，则扩展服务非常有用。使用extends你可以在一个地方定义一个通用的服务选项集然后在任何地方引用它。

注意：不能使用extends来共享links, volumes_from和depends_on配置。这是为了避免隐式依赖 – 始终在本地定义links和volumes_fromm。这确保了当读取当前文件时服务之间的依赖是清晰可见的。在本地定义这些还确保对引用文件的更改不会导致破坏。

理解extends配置

当在docker-compose.yml定义任何服务时，可以像这样声明扩展另一个服务：

这告诉compose重用定义在comm-services.yml文件的webapp服务配置。假设common-services.yml看起来像这样的：

在这种情况下，docker-compose.yml中定义的web服务将与webapp配置一样。

我们可以进一步在本地定义(或重新定义)docker-compose.yml:

也可以定义其它服务并在web服务链接它们：

示例用例

当多个服务有一个通用的配置时，扩展单个服务非常有用。下面示例是有两个服务的compose app:一个web应用程序和一个queue worker。两个服务使用相同的代码和共享许多配置项。

在common.yml我们定义通用的配置：

在docker-compose.yml文件我们定义使用通用配置的具体服务：

添加和覆盖配置

compose从original服务复制配置到local服务。如果配置项定义在original服务和local服务中，local服务的值替换或扩展original服务的值。

对于单值选项如image,command或mem_limit，新值替换旧值。

注意：当使用的是version 1的compose文件格式时，build和image两个选项，在local服务使用一个选项会导致compose忽略另一个如果定义在original服务的选项。

例如，如果orginal服务定义了image: webapp且local服务定义了build: . 那么结果是服务有build: .选项没有image选项。

这是因为在verion 1文件中build和image不能一起使用。

对于多值选项ports,expose,external_link,dns,dns_search物tmpfs，compose连接两组值：

对于environment, labels, volumes和devices，compose以本地定义的值优先原则来合并它们：

在compose文件中引用环境变量

可以在compose文件中引用运行docker-compose所在的shell中的环境变量，如:

在容器中设置环境变量

可以在compose文件中的environment关键词下设置容器的环境变量，就像docker run -e VARIABLE=VALUE …:

将环境变量传递到容器

可以在compose文件中的environment关键词下定义一个环境变量而不赋值，就像docker run -e VARIABLE …:

容器中环境变量DEBUG的值是从执行compose文件所在的shell的同一个环境变量取得。

env_file配置选项

可以使用compose文件中的env_file选项从一个外部的文件传递多个环境变量到容器中，就像docker run –env-file=FILE …:

使用docker-compose run设置环境变量

就像docker run -e，可以使用docker-compose run -e为一次性容器设置环境变量：

也可以不赋值从shell变量中取值：

DEBUG的值是从执行compose文件所在的shell的同一个环境变量取得。

.env文件

可以在环境文件.env设置默认的环境变量，这些环境变量可以在compose文件引用：

当执行docker-compose up命令，上面定义的web服务将使用webapp:v1.5镜像。可以使用config命令来打印出来：

在shell中的环境变量将比定义在.env文件中的环境变量优先。如果在shell中设置了一个不同的TAG，镜像将使用shell中定义的而不是.env文件中的：

compose支持在执行docker-compose命令的所在目录的.env文件中声明默认的环境变量。

env文件每行声明一个变量，格式为VAR=VAL。以#开头的行会忽略，也包括空行。

注意：那些在存在于运行时的环境变量始终会覆盖定义在.env文件的变量。类似地，通过命令行参数传递的值也优先。

可以在compose文件引用环境变量，也可以定义下面的CLI变量：

COMPOSE_API_VERSION

COMPOSE_CONVERT_WINDOWS_PATHS

COMPOSE_FILE

COMPOSE_HTTP_TIMEOUT

COMPOSE_TLS_VERSION

COMPOSE_PROJECT_NAME

DOCKER_CERT_PATH

DOCKER_HOST

DOCKER_TLS_VERIFY